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Preface 


Document Objectives 

A procedure is modular if it follows rules and principles that permit it to be successfully linked with 
other procedures following the same rules and principles. The VAX-11 Guide to Creating Modular 
Library Procedures tells you how to follow the VAX-11 Modular Programming Standard, which 
summarizes these rules and principles. Following this standard will lead to more reliable programs, 
and reduce checkout time and maintenance effort. 

This manual is a tutorial guide to designing and coding modular procedures written in VAX-11 
MACRO, BLISS-32, VAX-11 BASIC, VAX-11 FORTRAN, or VAX-11 PASCAL. You can use these 
procedures for general programming. You can also include them in a procedure library, such as an 
object module library, shareable image, or shareable image library. 

The guide includes required and optional modular programming techniques, recommended style, 
and a description of how to install modular procedures in procedure libraries. 

Intended Audience 

This manual is intended for advanced system and applications programmers who are already familiar 
with VAX/VMS system concepts. Readers should be familiar with the VAX/VMS operating system and 
proficient in at least one language supported by VAX/VMS. 

Document Structure 

All chapters in this manual are tutorial. 

• Chapter 1 is an overview of modular programming and of libraries. It explains the options you have 
in creating your own procedures and libraries and how to determine the type of library you should 
create. 

• Chapter 2 explains how to design and document the interface between a modular procedure and its 
calling program. 

• Chapter 3 describes how procedures use storage and how to maintain modularity while using 
different types of storage. 



• Chapter 4 describes specific modular coding techniques in VAX-11 MACRO, BUSS-32, VAX-11 
BASIC, VAX-11 FORTRAN and VAX-11 PASCAL. This includes required and optional parts of the 
standard for initialization, resource allocation, passing strings, use of system services and invoking 
user action routines. 

• Chapter 5 describes how to signal and return error conditions from modular procedures. 

• Chapter 6 describes programming techniques that allow asynchronous system traps (ASTs) to occur 
without conflicting with executing modular procedures. 

• Chapter 7 describes how to insert or replace a procedure in a user-created object module library, 
shareable image, or shareable image library. 

The appendixes provide background information: 

• Appendix A is the VAX-11 Modular Programming Standard. It consists of required, optional, and 
recommended rules and principles. Required rules must be followed. Optional rules must be 
followed or documented in the procedure documentation as not being followed. Recommendations 
are suggestions for programming style, but are not necessary for procedures to be modular. 

• Appendix B details the VAX/VMS naming conventions. 

• Appendix C presents the notation for describing procedure parameters. 


Associated Documents 

The following documents are associated with this manual: 

• VAX-11 Run-Time Library Reference Manual 

• VAX-11 Run-Time Library User's Guide 

• VAX/VMS System Services Reference Manual 

• VAX-11 Linker Reference Manual 

• VAX-11 BASIC User's Guide 

• VAX-11 BASIC Language Reference Manual 

• VAX-11 FORTRAN User's Guide 

• VAX-11 FORTRAN Language Reference Manual 

• VAX-11 PASCAL User's Guide 

• VAX-11 PASCAL Language Reference Manual 

• VAX-1 1 MACRO User's Guide 

• VAX—7 7 MACRO Language Reference Manual 

• VAX-11 BUSS-32 User's Guide 

• VAX-11 BLISS—32 Language Guide 

For a complete list of all VAX-11 documents, including brief descriptions of each, see the VAX-11 
Information Directory. 


x 




Conventions 

Unless otherwise noted, all numeric values are decimal. 

Unless otherwise specified, all commands end with a carriage return. 

Lowercase characters indicate variable information; uppercase characters indicate literal information, 
which you must enter exactly as shown. 

Brackets ([ ]) in procedure descriptions indicate optional arguments. An equal sign after an optional 
parameter indicates the default value. 

Ellipses (...) indicate parameters that can be repeated one or more times. 

Unless otherwise specified, the term: 

• MACRO means VAX-11 MACRO. 

• BLISS means BLISS-32. 

• BASIC means VAX-11 BASIC. 

• FORTRAN means VAX-11 FORTRAN. 

• PASCAL means VAX-11 PASCAL. 

• Run-Time Library means VAX—11 Common Run-Time Procedure Library. 

• Linker means VAX-11 Linker. 

In diagrams, the following conventions are used: 

■■■» control path 

-► data path 

— interface 




Summary of Technical Changes 


This manual is intended to accompany VAX/VMS Version 3.0. This section summarizes the technical 

changes from Version 2.0. 

• Chapters 1 and 7 have been revised to reflect changes in the operation of the VAX-11 Linker. You 
can now group shareable images in a shareable image library. 

• VAX/VMS now supports varying-length text strings. Section 4.5, Passing Strings as Parameters, has 
been revised to reflect this change. 

• The following have been added to the list of supported data types (see Appendix C, Notation for 
Describing Procedure Parameters): 

vu Variable-length bit field, unaligned 

vt Varying character-coded text string 

blv Bound label value 

adt Absolute date and time 

• The following have been added to the list of acceptable parameter forms (see Appendix C, Notation 
for Describing Procedure Parameters): 

x7 Either fixed-length or dynamic descriptor, as indicated by the descriptor 

vs Varying string descriptor 

vs Varying string array descriptor 

ub Unaligned bit string descriptor 

uba Unaligned bit array descriptor 



Chapter 1 

Modular Procedures and Procedure Libraries 


A procedure is a set of related instructions that performs a task. Typically, a procedure is invoked by 
executing a VAX-11 CALLS or CALLG instruction. VAX-11 languages define a procedure as follows: 


MACRO 

BLISS 

BASIC 

COBOL 

FORTRAN 

PASCAL 

PL/I 


A procedure begins with .ENTRY and ends with END 
A procedure is declared as a ROUTINE with the default linkage 
A procedure is a main program, subprogram, or function 
A procedure is a main program or subprogram 
A procedure is a main program, subroutine, or function 
A procedure is declared as a procedure or function 

A procedure is a program unit consisting of a procedure or function heading and a 
block 


A procedure is modular if it follows rules and principles that permit it to be successfully linked 
together in arbitrary ways with other procedures that follow the same rules and principles. These rules 
and principles are summarized in the VAX-11 Modular Programming Standard, contained in 
Appendix A of this manual. 

This manual describes how to perform a complex task by dividing it into modules and coding each 
module as a separate procedure. This kind of modular programming offers several advantages over 
writing a complex program as a single source module: 

• You can use any modular procedure in any program. 

• You can add a modular procedure to a library at any time. 

• You need not rewrite common algorithms every time a new program needs them. 

• You can divide a complex program into simpler procedures to reduce development time, reduce 
complexity, and increase reliability. 
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• You can modify or replace a procedure without modifying the calling program. 

• You can control process-wide resource allocation. 

• You can use different programming languages to write different procedures for a program. 

The Modular Programming Standard also contains optional elements and recommendations. If you 
follow these elements, you will gain other advantages: 

• Shareable library procedures can save memory and link time. 

• AST-reentrant procedures can be called by AST-level procedures. 

• Modular procedures that conform to all coding recommendations are similar in format and there¬ 
fore are easier to use and maintain. 

• Structured programming recommendations let your procedures work together in a logical pattern. 

You can use modular procedures for general programming or you can group them in procedure 
libraries. Libraries are simply a way of collecting procedures so that calling programs can access them 
easily. When you link your program to a library, any reference that the program makes to a procedure 
in the library is automatically resolved by the VAX-11 Linker. This means that your program can call 
many modular procedures without having to include each one explicitly in the LINK command. The 
program's executable image and the procedures that it calls are executed in the proper sequence at 
run time. 

Figure 1-1 shows the development of a program that calls one or more procedures in a library. 
Depending on the options you select when writing modular procedures, you can control the way the 
linker accesses your procedures and thus the way procedures are invoked at run time. For example, 
placing commonly used procedures within a shareable image or shareable image library saves 
memory and disk space, because all user processes access a single copy of the procedure. 

Note 

Much of this manual refers to libraries of procedures. However, the same principles 
apply to writing modular procedures in general. 


1.1 Designing and Coding Modular Procedures 

To ensure that your procedures are truly modular, that is, that they are compatible with other proce¬ 
dures and programs executing on VAX/VMS, you should follow the programming rules and recom¬ 
mendations described in this manual. The VAX-11 Modular Programming Standard (Appendix A) 
summarizes these techniques, which DIGITAL uses to develop VAX/VMS library software. 

The Modular Programming Standard includes: 

• Those elements of the VAX—11 Procedure Calling Standard that ensure the modularity of 
procedures 

• Additional techniques and recommendations for modular programming 

Once you have written a modular procedure, you can link it as a shareable image so that other 
processes can use it more efficiently. You can also place it in an object module library, a shareable 
image library, or both. See Chapter 7. 
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Developing a Program That Calls Library Procedures 


Figure 1—1: 
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Appendix A contains the Modular Programming Standard. Chapters 2 through 6 of this manual 
explain the standard and describe how to use it to write modular procedures. The standard includes 
three types of elements: 

• Required elements. You must follow these rules to ensure modularity. 

• Optional elements. If you do not follow an optional element of the standard, you must state in the 
documentation for the procedure that you are not following the element. 

• Recommendations. Following these provisions makes it easier for your modules to be used by 
others. However, they are not necessary for modularity. 

1.1.1 Summary of the Modular Programming Standard 

The remaining chapters in this manual describe the following major aspects of the Modular 
Programming Standard: 

• Storage 

Procedures can use static, heap, or stack storage. Chapter 3 explains these types and provides 
principles to be followed when using them. 

• Naming rules and recommendations 

Section 2.2 describes naming rules for procedures, modules, and program sections (PSECTs). Sec¬ 
tion 4.2 explains the naming recommendations for file names. 

• Process-wide resource allocation 

Process-wide resources include virtual memory, logical unit numbers, event flags, and dynamic 
strings. You can also create additional resources. Section 4.4 describes the available resources and 
allocation methods. 

• Use of system services 

Modular procedures can use system services that conform to the modular programming standard. 
Section 4.6 lists all system services and indicates those that modular procedures can use. 

• Signaling and condition handling 

Chapter 5 describes the programming rules for signaling and condition handling as well as tech¬ 
niques for signaling between related procedures. 

• AST—reentrant procedures 

VAX/VMS provides a mechanism to interrupt image execution in response to an external asynchro¬ 
nous event. When the event occurs, a user-supplied asynchronous system trap (AST) routine is 
called. 

An AST-reentrant procedure can be interrupted and reexecuted before resuming execution at the 
point of the interrupt. Thus, it can be called from both AST-level and non—AST-level routines. 
Most modular procedures are AST—reentrant. Chapter 6 describes how to write AST—reentrant 
modular procedures. 

• Position-independent code 

Position-independent code executes correctly no matter where it is placed in the virtual address 
space after it is linked. To be modular, a shareable image must contain position-independent code. 
The data required by the procedure, however, does not need to be position-independent. 

The VAX-11 Linker Reference Manual discusses position-independent code in detail. 


1—4 Modular Procedures and Procedure Libraries 





• Transfer vectors 

A transfer vector is a labeled virtual memory location that contains an address of, or a displacement 
to, a second location in virtual memory. When a shareable image is referenced by means of a 
transfer vector, a program that calls procedures in the shareable image does not need to be relinked 
every time a new version of the shareable image is installed. It is recommended that you include 
transfer vectors when you design a shareable image. However, you can add transfer vectors to 
procedures in a shareable image at any time. Chapter 7 explains how to create transfer vectors. 

1.1.2 Checklist of Design and Coding Steps 

You should follow the steps outlined in this checklist when you design and code modular procedures 
and when you design the interface between a program and the modular procedures that it calls. 

The section numbers indicate where you can find detailed information. 

1. Select procedure name(s) and facility name (Section 2.2). 

2. Define a procedure's explicit parameters (Section 2.3). 

3. Choose these characteristics for each explicit parameter (Sections 2.3.1 and 2.3.2): 

• Access type 

• Data type 

• Passing mechanism 

• Parameter form 

4. Place the parameters in the calling sequence in the correct order (Section 2.3.6). 

5. Decide whether and how the procedure will retain information from one activation to another 
(Section 2.4). 

6. Determine how procedures will indicate error and success conditions (Section 2.3.7 and 
Chapter 5). 

7. Provide optional action routines if your procedure produces human readable output to a charac¬ 
ter imaging device (Section 2.6). 

8. Provide statistic and status entry points for any resource allocation procedure (Section 2.7). 

9. Write documentation for procedures and modules (Section 2.8): 

• Write module descriptions 

• Write procedure descriptions 

10. Decide how each procedure will utilize storage. Determine the type of storage to be used and 
steps required to maintain modularity (Chapter 3). 

11. Consider structured programming recommendations (Section 4.1). 

Decide: 

• The number of procedures involved 

• How they interact with each other 
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• How they are arranged in modules 

• Whether they are potentially shareable 

12. Check Appendix A for the complete list of required, optional and recommended elements of the 
modular programming standard before coding procedures. 

13. Determine what resources your procedure will need. If a resource allocation procedure does not 
exist for the resources you need, write one and add it to an object module library (Section 4.4). 

14. Code each procedure to handle error conditions (Chapter 5). 

15. Decide whether to make procedures AST-reentrant (Chapter 6). 

16. Follow coding rules and recommendations while writing code (Section 4.1). Be sure to follow the 
standard in these areas: 

• Initialization (if needed) (Section 4.3) 

• Use of system services (if needed) (Section 4.6) 

• Passing string parameters (if needed) (Section 4.5) 

17. While fixing bugs in your procedures, be sure to maintain modularity. 

18. Add debugged procedures to an object module library, install as a shareable image, or add to a 
shareable image library, as required. If you install the procedures as a shareable image, you 
should also install them in an object module library (Chapter 7). 

1.2 Using and Creating Libraries 

VAX/VMS allows you to group procedures into libraries. When you link a program with a library, the 
linker automatically searches that library for procedures that your program calls. This allows your 
program to access groups of procedures without explicitly linking each procedure each time you 
need it. 

You can group procedures in one of three ways: 

• As an object module library. When a program issues a call to a procedure in an object module 
library, the linker copies and links the module containing the procedure into the calling program's 
object file. The module and the program then become a single executable image. 

• As a shareable image. When a program calls a procedure in a shareable image, the linker creates 
linkages between the program and the procedures in the shareable image. The shareable image is 
not copied into the executable image. Instead, it is mapped into the process address space at run 
time. 

• As a shareable image library. When a program calls a procedure in a shareable image library, the 
linker resolves the reference to the procedure by searching the entire library. If it finds the shareable 
image referenced in the library, the code is executed at run time. 
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Chapter 7 of this manual tells you how to create shareable images, shareable image libraries, and 
object module libraries. 

DIGITAL supplies several libraries with VAX/VMS. For example, the VAX-11 Common Run-Time 
Procedure Library is a set of modular procedures that provide support for components of the 
VAX/VMS system. Many Run-Time Library procedures are called implicitly at run time by other 
system components, such as high-level language compiled code. When you link your program, the 
linker automatically searches the Run-Time Library Library for unresolved references to global sym¬ 
bols. The search operation takes place as follows: 

1. The linker includes in a single executable image your program's object file and any other object 
files that you specify explicitly in the LINK command. 

2. If you have specified a shareable image in an options file and named the options file in the LINK 
command, the linker resolves references using this image. 

3. The linker searches any object module library or shareable image library you have specified. If 
the linker finds an object module in which a reference is resolved, it copies the module into the 
image. If the linker finds a shareable image in which a reference is resolved, it creates linkages to 
the shareable image so that the shareable module can be called at run time. If you specify more 
than one library, the linker searches them in the order you have named them. 

4. The linker automatically searches the default shareable image libraries. If it resolves references 
with one of the default shareable images listed in IMAGELIB.OLB, it includes that shareable 
image. 

5. The linker automatically searches STARLET.OLB, the default object module library, if any unre¬ 
solved references remain. If modules in STARLET.OLB resolve any of those references, the linker 
copies the modules into the image. 

You can change the default searching operation of the linker by specifying the qualifiers /NOSYSSHR 
or /NOSYSLIB in the LINK command. When you include /NOSYSSHR, the linker omits the search of 
IMAGELIB.OLB and only searches STARLET.OLB to resolve references. Thus any object modules it 
finds are copied into the executable image. If you include /NOSYSLIB, the linker searches neither 
STARLET.OLB nor IMAGELIB.OLB. If you wish the linker to search IMAGELIB.OLB and 
skip the search of STARLET.OLB, specify the following in the LINK command: /NOSYSLIB 
SYS$LIBRARY:IMAGELIB/LIBRARY. 

The executable image that results from these steps can be executed in your process with the RUN 
command. If you do not name any shareable images or libraries as explicit inputs to the linker, the 
linker still searches the default libraries automatically. Thus, if you include calls to Run-Time Library 
procedures in your program, you do not need to link your program to the Run-Time Library explicitly. 

Figure 1-2 shows the VAX/VMS libraries, including the default object module library, STARLET.OLB, 
and the default shareable image libraries. These libraries contain most of the Run-Time Library 
procedures. 
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Figure 1-2: DIGITAL-Supplied Libraries 
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Chapter 2 

Designing Modular Procedure Interfaces 


If the interface between each procedure and its caller is modular, then any procedure can fit together 
with any other group of procedures in a program. If you follow the design techniques described in this 
chapter, your procedures will operate successfully with other modular procedures. For a complete 
checklist of steps for modular programming, see Chapter 1. 

This chapter discusses the following design aspects: 

• Procedure names 

• Explicit parameter types and passing mechanisms 

• Implicit parameters 

• Documentation of procedure functions 

• Control of human readable output 

• Timer and resource allocation procedures 

This chapter describes three types of techniques: required, optional, and recommended. Required 
rules and principles must be followed to ensure modularity. Optional rules and principles require 
documentation if not followed. Following the recommendations makes your procedures more 
uniform and easier to use. 


2.1 Procedure Names 

Entry point naming standards follow the VAX—11 standards for naming global symbols. A global 
symbol takes the general form: 

fac$symbol (DIGITAL-supplied) 

fac_symbol (User-created) 
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where: 

fac 

is a three-character facility name, 
symbol 

is a symbol from one to 27 characters long. (The entire global symbol cannot exceed 31 charac¬ 
ters in length.) 

A symbol generally consists of a verb followed by the object. Together, verb and object describe the 
procedure's action. Thus the library procedure that is intended to get virtual memory is called 
LIB$GET_VM. The facility name and the character symbol are separated by a single dollar sign if the 
procedure is supplied by DIGITAL and by an underscore if the procedure is created by a user. This 
convention avoids conflict between DIGITAL and user procedure names. 

Some global procedures are not intended to be part of the modular interface and are available only 
internally, within a set of procedures. These procedures' names are differentiated by a double dollar 
sign if they are DIGITAL—supplied, and by a triple underscore if they are user-created. Three under¬ 
scores are necessary to differentiate user-created internal global entry point names from user-created 
condition value symbols, which use two underscores. 

Entry point names of procedures called only from inside the same module need not include the 
facility name, provided the entry point names are not global symbols. 

2,1.1 Facility Names 

The DIGITAL—defined facility names are registered in a system-wide registry maintained by DIGITAL. 
For example, the VAX-11 Run-Time Library uses the following facility names: 

General utility facilities: 

LIB General purpose 

MTH Mathematics 

STR Strings 

OTS Language-independent support 

Language support facilities: 


BAS 

BASIC support 

COB 

COBOL support 

FOR 

FORTRAN support 

PAS 

PASCAL support 

PLI 

PL/I support 


For language support, the facility name is generally the same as the default file type for source files 
written in the language. Appendix B lists other available facility names. 

You can also create your own facility names if none of the DIGITAL-defined ones are appropriate. 
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2.1.2 Condition Value Symbols 

Condition value symbols symbolically define unique, system-wide, 32-bit condition values. These 
values are used in return status codes, in signal argument lists, and as message identifiers. Condition 
value symbols have the following general form: 

fac$-symbol (DIGITAL-supplied) 

fac_symbol (user-created) 

A unique, 12-bit facility number is assigned to each facility name for the facility number field in a 
condition value. For a list of these numbers, see the VAX-11 Run-Time Library User's Cuide. 

2.1.3 Creating Your Own Facilities 

You can create your own facilities by defining a unique facility name and facility number. Bit 27 
(STS$V_CUST_DEF) of a condition value indicates whether that value is user- or DIGITAL-supplied. 
This bit must be 1 if the facility number is user-created. 


2.2 Explicit Parameters 

Explicit parameters are a procedure's primary interface with other programs. Therefore, rules for 
parameter types and passing mechanisms must be carefully followed to maintain a modular interface. 

2.2.1 Parameter Characteristics 

Every parameter has these characteristics: 

• Access type 

• Data type 

• Passing mechanism 

• Parameter form 

Table 2-1 lists the possible characteristics and their abbreviations. Appendix C, Notation for Describ¬ 
ing Procedure Parameters, describes each characteristic in detail. This list is complete for all charac¬ 
teristics allowed by the VAX-11 Procedure Calling Standard. 

The letter abbreviations following the parameter name are shorthand notations for the characteristics 
of each parameter. This notation is also used in program documentation and in the VAX-11 
Run-Time Library documentation set. A complete parameter description consists of five fields: 

<name> .<access type> <data type> .<passing mechanism> <parameter form> 

For example, the documentation for the calling sequence of LIB$GET_INPUT is: 
ret-status.wlc.v = LIB$GET_INPUT (get-str.wt.dx [,prompt-str.rt.dx [,outlen.ww.r]]) 
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Parameters enclosed in square brackets are optional. The notation indicates that a call to 
LIB$GET_INPUT requires one parameter; the other two are optional. The parameters have the 
following characteristics: 


g et-str 

Access mode 
Data type 

Passing mechanism 
Parameter form 


<w>rite only 

ASCII <t>ext (character) string 
by <d>escriptor 

<x > means that the parameter form (in this case, the descriptor class) is 
specified by the descriptor 


prompt-str (optional) 
Access mode 
Data type 

Passing mechanism 
Parameter form 


<r>ead only 

ASCII <t>ext (character) string 
by <d>escriptor 

<x > means that the parameter form (in this case, the descriptor class) is 
specified by the descriptor 


outlen (optional) 

Access mode 
Data type 

Passing mechanism 
Parameter form 


<w>rite only 
<w>ord integer 
by <r>eference 
not applicable 


Table 2—1: Procedure Parameter Characteristics 


<access type> 

c 

Call after stack unwind 

f 

Function call (before return) 

j 

JMP (after unwind) access 

mm 

Modify access 


Read-only access 


Call without stack unwinding 

H 

Write-only access 


<data type> 

a 

Virtual address 

arb 

8—bit relative virtual address 

arl 

32-bit relative virtual address 

arw 

16-bit relative virtual address 

b 

Byte integer (signed) 

bpv 

Bound procedure value 

bu 

Byte logical (unsigned) 

c 

Single character 

cit 

COBOL intermediate temporary 

cp 

Character pointer 

d 

Double precision D_floating 

dc 

D_floating complex 


(continued on next page) 
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Table 2-1: Procedure Parameter Characteristics (Cont.) 


<data type> (Cont.) 

dsc 

Descriptor (used by descriptors) 

f 

Single precision F_floating 

fc 

F_floating complex 

g 

Double precision G_floating 

gc 

G_floating complex 

h 

Quadruple precision H_floating 

he 

FH_floating complex 

1 

Loingword integer (signed) 

Ic 

Longword return status 

lu 

Longword logical (unsigned) 

nu 

Numeric string, unsigned 

nl 

Numeric string, left separate sign 

nlo 

Numeric string, left overpunched sign 

nr 

Numeric string, right separate sign 

nro 

Numeric string, right overpunched sign 

nz 

Numeric string, zoned sign 

o 

Octaword integer (signed) 

ou 

Octaword logical (unsigned) 

P 

Packed decimal string 

q 

Quadword integer (signed) 

qu 

Quadword integer (unsigned) 

r 

Record 

t 

Text (character) string 

u 

Smallest addressable storage unit 

V 

Bit (variable bit field) 

vs 

Varying string 

vt 

Varying text string 

w 

Word integer (signed) 

wu 

Word logical (unsigned) 

X 

Data type in descriptor 

z 

Unspecified 

zi 

Sequence of instruction 

zem 

Procedure entry mask 





<passing mechanism> 

d 

By descriptor 

r 

By reference 

V 

By immediate value 



<parameter form> 


Scalar 

a 

Array reference or descriptor 

d 

Dynamic string descriptor 

nca 

Noncontiguous array descriptor 

P 

Procedure reference or descriptor 


(continued on next page) 
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Table 2-1: Procedure Parameter Characteristics (Cont.) 


<parameter form> (Cont.) 

s 

Fixed length string descriptor 

sd 

Scalar decimal descriptor 

uba 

Unaligned bit string array descriptor 

ubs 

Unaligned bit string descriptor 

vs 

Varying string descriptor 

vsa 

Varying string array descriptor 

X 

Any valid descriptor class, as 


specified in descriptor 

X1 

Class s or d, as specified in 


descriptor 


2.2.2 Library Facility Passing Mechanisms 

Each library facility follows a particular set of conventions for passing mechanisms and data forms. If 
you use one of the facilities that has already established a technique, you should follow its guidelines. 
For example, when a program calls a procedure in the LIB facility, it passes all input scalars by 
reference. For more information on how Run-Time Library procedures pass parameters, see the 
VAX-11 Run-Time Library User's Guide, Chapter 2. 

2.2.3 Parameter Passing Mechanisms 

By default, most high-level languages pass atomic data types by reference and strings by descriptor. If 
a modular procedure is to be called explicitly from higher-level language programs, it should use the 
same conventions, so that there is no need for language extensions in the calling program. For this 
reason, the LIB, MTH, and STR facilities of the Run-Time Library accept atomic data types by 
reference rather than by immediate value, and strings by descriptor rather than by reference. Note 
that the calling technique required by the modular programming standard differs from the calling 
technique for VAX/VMS system services; system services accept atomic data type input parameters by 
immediate value, not by reference. 

2.2.4 String Descriptors 

The calling program passes strings by descriptor to every library facility. For information on passing 
strings as parameters, see Section 4.5 and the VAX—11 Run-Time Library User's Guide. 

2.2.5 Optional Parameters 

An optional parameter is one that the calling program can omit. The calling program indicates the 
omission by passing argument list entries containing zero. For a trailing optional parameter, the 
calling program can pass a shortened list or a zero argument list entry. 

Note 

VMS System Services, unlike the Run-Time Library, cannot accept a shortened argu¬ 
ment list. Omitted arguments must always be indicated with a zero argument list 
entry. 

For parameters passed by immediate value, there is no distinction between passing an 
argument whose value is zero and omitting an argument. In both cases, the argument 
is considered to be omitted. 
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2.2.6 Order of Parameters 

Procedures in the Run-Time Library follow a consistent pattern for positioning parameters. You 
should follow the same guidelines. Group procedure parameters from left to right in this order: 

1. Required input parameters (read access) 

2. Required input-output parameters (modify access) 

3. Required output parameters (write access) 

4. Optional input parameters (read access) 

5. Optional input-output parameters (modify access) 

6. Optional output parameters (write access) 

Note that optional parameters follow required parameters. In this way, when the calling program 
omits the optional parameters, the actual argument list passed to the procedure is shortened. 

The called procedure accesses the required parameters from left to right, beginning with the first 
parameter. The only exceptions are procedures that return a function value longer than 64 bits, such 
as strings or H_floating values. Most function values are returned in in the first two registers, R0/R1. 
However, when the function value exceeds 64 bits, it is too large to be returned in R0/R1. In this 
case, the calling program uses the first parameter to specify where the function value is to be stored, 
and the other parameters are shifted right one position. (See the VAX-11 Procedure Calling Standard.) 

2.2.7 Error and Condition Values 

There are two ways for a procedure to indicate errors to its calling program: 

• Return a condition value as a completion code 

• Signal the error 

It is recommended that modular procedures return a completion code as a function value whenever 
possible. Then, when an error occurs, the completion code indicates the error to the the procedure's 
calling program. The caller can choose a specific recovery path for each procedure that it calls. 

For a description of signaling, see Chapter 5. The calling program recovers more easily from an error 
that is signaled than from one returned as a function status. However, when a program signals, it must 
associate the same error recovery action with all the procedures that it calls. 

Procedures in the following facilities of the Run-Time Library handle errors as follows: 

LIB Always returns completion code. 

MTH Always signals errors (function value is the mathematical value returned). 

OTS Returns completion code when a check of the code will not impose an excessive 
STR speed or space penalty on the caller; otherwise, it signals the error. 

FOR 

PAS 

COB 

BAS Signals I/O errors. For other errors, returns completion code when a check of the code 
will not impose an excessive speed or space penalty on the caller; otherwise, it signals the 
error. 
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2.3 Implicit Parameters 

In addition to explicit parameters, there can be parameters that are not specified in the parameter list. 
These implicit parameters provide additional information to your procedure from static storage loca¬ 
tions. There are two types of implicit parameters: 

• Those allocated by the calling program 

• Those allocated by your procedure 

When deciding whether your procedure will have implicit parameters, you should consider the 
advantages and disadvantages discussed in the following sections. If you do not use implicit parame¬ 
ters, modularity is easier to maintain. If your procedure must retain information from previous activa¬ 
tions and you want to avoid using implicit parameters, read Section 2.4. If you must use implicit 
parameters, read the rest of this section and the discussion of static storage in Chapter 3. 


2.3.1 Implicit Parameters Allocated by the Calling Program 

The calling program can allocate two types of implicit parameters: 

• Statically allocated variables in a named PSECT (for example, COMMON and MAP in BASIC, 
COMMON in FORTRAN, or variables declared in the outer block of a procedure or program in 
PASCAL) 

• Statically allocated global variables (for example, symbols defined with a double colon [::] in 
MACRO, and GLOBAL variables in BLISS) 

There are several disadvantages to using implicit inputs allocated by the calling program: 

• Two programs could use the same PSECT name or global variable for different values. This error 
will be undetected. 

• The calling program is no longer independent of the called procedure, as a change in one could 
inadvertently affect the other. 

• In BASIC and FORTRAN, the calling program has to declare all of COMMON regardless of the 
number of implicit inputs actually needed. 

• If your procedure is put in a shareable image, it cannot be called from outside the shareable image, 
since the shareable image cannot reference implicit parameters that are outside of itself. 

Because of these restrictions, allocation of implicit parameters by the calling program violates the 
Modular Programming Standard. 

2.3.2 Implicit Parameters Allocated by the Called Procedure 

One type of implicit parameter is allocated by the called procedure: local static storage. The proce¬ 
dure declares static storage using .BYTE through .QUAD in MACRO, OWN in BLISS, and all varia¬ 
bles in FORTRAN. BASIC and PASCAL do not have the notion of static storage that satisfies modular 
programming requirements. 
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Implicit inputs retained in local static storage usually keep track of resources (using resource allocat¬ 
ing procedures) and shorten the explicit parameter list. However, the use of implicit inputs by non¬ 
resource-allocating procedures can lead to unexpected results. Assume that procedure A is to leave 
information for a companion procedure B. Thus, B has both explicit inputs (from its caller) and 
implicit inputs (from A's storage). Next, consider that a calling program calls A, then calls procedure 
X, and finally calls B. For the calling program to get correct results from B, it must know that X (and 
any procedure that X calls) did not make a call to A (since such a call would change the implicit 
inputs A leaves for B). 

In the following FORTRAN example, LIB_GET_STRING reads a string from the terminal; 
LIB_GET_STR_LEN, a companion procedure, returns the length of the string last read by 
LIB_GET_STRING. 


C Procedure to Read String from Terminal 

FUNCTION LIB_GET_STRING (LEN) 

INTEGER*^ LENGTH ! Place to remember length 

CHARACTER() LIB_GET_STRING 

READ 100» LENGTH * LIB_GET_STRING 

100 FORMAT (Qt A) ! Set LENGTH to length of line input 

RETURN 

C Procedure to Return Length of String Last Read 

ENTRY LIB_GET_STR_LEN 

LEN = LENGTH ! LENGTH is implicit input parameter 

RETURN 

END 


This calling program could get unexpected results if procedure X also happens to call 
LIB_GET_STRING. Instead of getting the length of the string read in statement 1000, statement 2000 
uses the length of the string read in procedure X. 


CHARACTER*G0 NAME 
1000 NAME = LIB_GET_STRING () 

CALL X (♦♦♦) 

2000 ♦ ♦ ♦ = NAME (1:LIB_GET_STR_LEN( ) ) 


Figure 2-1 illustrates this situation pictorially. 

One of the objectives of modular programming is to permit procedures to be combined arbitrarily 
without needing to understand each other's internal workings. Therefore, the use of such implicit 
parameters violates the modular programming standard. The problem discussed previously will also 
occur if X is rewritten to include a call to A. In that case, a calling program that assumes the old 
version of X would get incorrect results on its call to B. 

Furthermore, the same problems can occur with any non-resource-allocating procedure that leaves 
results for itself as future implicit parameters. 

The following section describes how to avoid the problems of implicit input parameters allocated by 
the calling program or the called procedure. 
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Figure 2—1: How Implicit Inputs Can Violate Modularity 



-— CONTROL PATH 

-— DATA PATH 

MK-00684—00 


2.4 How to Avoid Implicit Parameters 

There are four ways to write non-resource-allocating procedures that avoid the implicit parameter 

problems described in Section 2.3: 

• When one procedure obtains results from another, combine the two procedures into a single call 
(see Section 2.4.1). 

• Provide a single call to an action routine supplied by the calling program part way through your 
procedure's execution (see Section 2.4.2). 

• Give the calling program responsibility for retaining information from a procedure activation. This 
is done with an explicit parameter (see Section 2.4.3). 

• Design an interface consisting of a sequence of calls to different procedures. The first call saves the 
contents of any still-active implicit parameters on a pushdown stack in heap storage. The last call 
restores the old implicit parameters. This technique allows a sequence of procedures to use static 
storage to pass implicit inputs from one procedure to another (see Section 3.3.3). 
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2.4.1 Combining Procedures 


Often non-resource-allocating procedures that leave results for one another can be combined into a 
single procedure that returns all information explicitly in a single call. Consider the example of the 
companion procedures LIB_GET_STRING and LIB_GET_STR_LEN from Section 2.3.2. 

If LIB_GET_STRING and LIB_GET_STR_LEN are changed into a single procedure, procedure X can 
no longer modify LIB_GET_STRING's storage before the length can be returned. 


C Procedure to Read String from Terminal 
FUNCTION LIB_GET_STRING (LEN) 

CHARACTER() LIB_GET_STRING 
READ 100> LEN * LIB_GET_STRING 

100 FORMAT (0 » A) !Set LENGTH to length of line input 

RETURN 
END 


This calling program obtains both the string and its length in a single call, thereby preventing proce¬ 
dure X from causing unexpected side effects. 


CHARACTER*G0 NAME 

1000 NAME = LIB_GET_STRING (NAME_LEN) !set NAME.LEN to length of NAME 
CALL X ( ♦ ♦ ♦ ) 

2000 .♦♦ = NAME (1:NAME_LEN) 


2.4.2 User Action Routine 

Another way to combine several procedures into one call is to let the calling program gain control at 
a critical point in your procedure's execution. To do this, your procedure must specify an action 
routine parameter that will be called in the middle of your procedure's execution. Thus, your proce¬ 
dure can execute twice, before and after the action routine, with no implicit inputs. BASIC and 
FORTRAN OPEN statements use this technique by permitting the user to supply a USEROPEN action 
routine. 

To keep the calling program from having to provide implicit inputs for its action routine, your 
procedure should also provide another parameter that is passed along to the action routine. The 
calling program uses the following calling sequence to invoke your procedure: 

CALL my-proc (... ,action-routine.flc.rp,user-arg.xy.z) 

Then your procedure invokes the action routine as follows: 

CALL action-routine (... ,user-arg.xy.z) 

See Section 4.7 for an example of the code to invoke a user action routine. 


Note 

The argument data type and argument passing mechanism provided by the calling 
program are immaterial to your procedure. Your procedure copies the 32-bit argu¬ 
ment list entry, as is, to the action routine. 
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One restriction on using action routines is that FORTRAN and PASCAL pass procedures as parameters 
using different passing mechanisms. In FORTRAN, the argument list entry contains the address of the 
entry mask of the action routine. In PASCAL, the argument list entry contains the address of the entry 
mask of the action routine and an environmental pointer. 

The VAX-11 Procedure Calling Standard defines Entry Mask (ZEM) and Bound Procedure Value (BPV) 
data types. However, a language extension to PASCAL permits the BPV data type to be passed by 
immediate value, making it identical to ZEM. 

A second restriction is that your procedure cannot be written in BASIC. However, the calling program 
can pass a reference to an external symbol naming an action routine. This technique achieves the 
effect of the ZEM data type. 

Often it is convenient for the calling program to specify your procedure in such a way that either the 
action-routine parameter or the user-arg parameter, or both, are optional. However, only a called 
procedure written in MACRO or BLISS can test for optional parameters. 

2.4.3 Designating Responsibility to the Calling Program 

You can give the calling program responsibility for retaining information from one procedure activa¬ 
tion to another. You can do this in three ways: 

• Require the calling program to allocate the storage your procedure needs. Then have the calling 
program pass the address of the storage location as an explicit parameter on all calls to your 
procedure (see Section 2.4.3.1). 

• Require the calling program to allocate a longword pointer to the stored data and pass its address to 
your procedure as an explicit parameter. On the first call, your called procedure will dynamically 
allocate storage (by calling LIB$GET_VM) and store its address in the caller's longword. On subse¬ 
quent calls, your procedure will use information left in the storage area from previous calls (see 
Section 2.4.3.2). 

• Require the calling program to pass a process-wide identifying value to your procedure on all calls. 
The process-wide identifier indicates which information from previous procedure activations is to 
be used as implicit inputs (see Section 2.4.3.3). 

Figure 2—2 shows a calling program with responsibility for explicitly indicating the storage to be used 
by the called procedure. The following sections show the three ways to do this. 


2.4.3.1 Calling Program Allocates Procedure Storage — In this method, the calling program allocates 
all storage needed and passes the address of the storage as an explicit parameter on each call. 

For example, the library procedure MTH$RANDOM requires that the calling program allocate stor¬ 
age for the longword seed and pass its address on each call. The calling sequence is: 

value.wf.v = MTH$RANDOM (seed.ml.r) 

MTH$RANDOM takes the seed as input and computes the next random number sequence from the 
current seed value. MTH$RANDOM returns a random number between 0 and 1. It also updates the 
longword seed passed by the calling program. This ensures that the procedure will generate a differ¬ 
ent value on the next call (the code is shown in Section 3.3.2). 
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Figure 2-2: Designating Storage Responsibility to the Caller 



INTERFACE 


storage, you can separate information 


stored on each procedure activation 


_ and prevent undetected conflicts. 

-DATA - CONTROL 

= = = = :> PATHS > PATHS 


MK-00685—00 

The disadvantage of this method is that you cannot increase the amount of storage needed by your 
procedure without requiring all calling programs to be rewritten. Thus, you should use this method 
only when you are confident that your procedure will not be revised in the future to use additional 
storage. 

The next two sections describe interface techniques that permit storage size to change without affect¬ 
ing the interface with the calling program. 

2.4.3.2 Calling Program Passes Pointer — In this method, the calling program allocates only a 
longword pointer to the dynamic heap storage to be allocated by your procedure. It then passes the 
address of the longword as an explicit parameter. There are two interface techniques to indicate that 
storage is to be initialized: 

• Provide a single entry point. If your called procedure finds the value zero in the longword that the 
calling program has allocated, the procedure allocates and initializes dynamic heap storage. 

• Provide a second entry point. This entry point stores in the longword the address of the allocated 
storage. On subsequent calls, your procedure uses that value as the storage address of information 
from previous calls. 
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Regardless of the method used to indicate storage allocation and initialization, you must also provide 
a way to indicate storage deallocation. You can do this with either a separate parameter or separate 
entry point. 

For example, the procedure LIB$INIT_TIMER, which gets times and counts from the operating sys¬ 
tem, uses a single optional parameter ( handle ) to determine where these values are to be stored. The 
calling sequence is: 

ret-status.wlc.v = LIB$INIT_TIMER ([handle.ml.r]) 
handle 

Address of a longword that points to a block of storage containing the values of times and counts. 
This parameter is optional. 

• If handle is missing, the values are stored in static storage, making this call non-AST-reentrant 
(see Chapter 6). 

• If handle is zero, LIB$INIT_TIMER allocates a block of dynamic heap storage by calling 
LIB$GET_VM. The values are placed in that block, and the address of the block is returned in 
handle. 

• If handle is nonzero, it is considered to be the address of a storage block previously allocated by 
a call to LIB$INIT_TIMER. The block is used again, and new times and counts are stored in it. 

The entry point LIB$FREE_TIMER deallocates the block of dynamic heap storage allocated by a 
previous call to LIB$INIT_TIMER. The calling sequence is: 

ret-status.wlc.v = LIB$FREE_TIMER (handle.ml.r) 

handle 

The address of a longword that points to a block of dynamic heap storage where times and counts 
have been stored. That storage is returned to free storage by calling LIB$FREE_VM. 

The LIB$ and STR$ string procedures that handle dynamic strings also use this method. They require 
that the calling program allocate space for the dynamic string descriptor (two longwords) and pass its 
address on each call. The second longword contains a pointer to heap storage. 

2.4.3.3 Calling Program Passes a Process-Wide Identifier — In this method, the calling program 
passes a process-wide identifying value to identify implicit results produced on previous calls which 
will be implicit inputs on this call. Any calling program can use the process-wide identifier. Examples 
of process-wide identifiers include BASIC or FORTRAN logical unit numbers and VAX/VMS system 
services I/O channel numbers. 

Process-wide identifiers are a resource. Modular programming techniques require that all resources 
allocated by a procedure be allocated by calling a resource-allocating procedure. This prevents 
conflicts, since a single procedure can keep track of multiple allocations to more than one procedure 
or procedure activation. Therefore, if you use the method described in this section, you will also have 
to write a resource-allocating procedure to control the resource. If you write a resource-allocating 
procedure, it is recommended that you place it in an object module library, so that other 
programmers can use it. 

The library procedures LIB$GET_LUN and LIB$FREE_LUN allocate and deallocate BASIC or 
FORTRAN logical unit numbers outside the range normally specified in user programs, that is, outside 
the range 0 to 99. An example of a resource-allocating procedure that allocates identifying numbers is 
given in Section 4.4.2. 
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2.5 Control of Human Readable Output 

A modular procedure allows its calling program to control human readable output sent to the termi¬ 
nal, queued to a line printer, or written to a file. You do this by providing an optional parameter that 
the calling program can use to specify an action routine. 

If the calling program specifies an action routine, your procedure calls the action routine with each 
record of output information, instead of outputting the record directly to a file or device. The action 
routine is called once for each record, using the address of a string descriptor as the parameter. The 
user-supplied action routine writes each record on any output device and returns a failure or success 
status to your procedure. If an error status is returned, your procedure stops calling the action routine 
and returns the same error status to the original calling program. 

When an action routine is called to print records, each record should not exceed 80 characters so it 
can be printed on most terminals. The record should begin with a space (FORTRAN convention) and 
contain no ASCII carriage return (CR) or line feed (LF) characters. Thus, the line can be written into a 
file having CR, FTN, or PRN record attributes. 

To help your caller write a single, multi-purpose action routine, your procedure should also provide 
an additional optional parameter which, if present, is passed to the action routine as a second 
argument. Then the calling program can pass information to the action routine that applies to 
each call. 

For example, you could create a procedure LIB_SNAP_SHOT that writes a memory dump on the 
output device LPAO unless the calling program supplied an action routine. The calling sequence is: 

ret-status = LIB_SNAP_SHOT (low-adr, high-adr [,user-act-rout [,user-arg]]) 

UB_SNAP_SHOT can be called from FORTRAN as follows to write the information to file 
DUMPOUT.DAT instead of device LPAO: 

EXTERNAL PROC 

OPEN (UNIT = 1 0 * FILE = 'DUMPOUT 7 ) 


IF 


(♦NOT♦ LIB_SNAP_SH0T (A# B(100) 


PROC)) GO TO 9999 


♦ 

END 

FUNCTION PROC (RECORD) 

CHARACTER() RECORD 
INTEGER*^ PROC 

PR0C = 0 ! Assume Error 

WRITE (10 m ERR=100) RECORD 
PRQC=1 (Success 

100 RETURN 
END 


Alternatively, LIB_SNAP_SHOT can be called as follows to output the dump on the controlling 
output device instead of LPAO: 

IF (♦N0T*LIB_SNAP_SH0T (At B(100)# LIB$PUT.OUTPUT)) 

See Section 4.7 for an example of the code to invoke a user action routine. See also Section 2.4.2 for 
a discussion of the considerations of using action routines in BASIC, FORTRAN, and PASCAL. 
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2.6 Timer and Resource Allocation Procedures 


All timer and resource allocation procedures should make statistics available for performance evalua¬ 
tion and debugging. These procedures are coded with two entry points: 

LIB$SHOW_name or LIB_SHOW_name 
LIB$STAT_name or LIB_STAT_name 

2.6.1 SHOW Entry Point 

A SHOW entry point provides formatted strings containing the information you want. It should follow 
the conventions for providing human readable output (see Section 2.5). The calling sequence is: 

ret-status.wlc.v = LIB$SHOW_name ([code.rl.r [,action-routine.flc.rp [,user-arg.xx.x]]]) 

code 

An optional code (of the form LIB$K_code) designating the statistic you want. Define a separate 
code for each statistic available; the codes are the same for the SHOW and STAT entry points. 
The values associated with the codes start at one for each procedure. The functional specification 
in the procedure's documentation should list the codes used. If the code is omitted or zero, the 
procedure provides all statistics. 

action-routine 

The address of an action routine. This is an optional parameter. If omitted, statistics are written to 
SYSSOUTPUT. 

user-arg 

An optional user parameter to be passed to the action routine. If omitted, a shortened list is passed 
to the action routine, user-arg , if present, is copied to the parameter list passed to the action 
routine. That is, the 32—bit argument list entry passed by the calling program is copied to the 
argument list entry passed to the action routine. Thus, the access type, data type, parameter form, 
and passing mechanism can be arbitrary, as agreed between the calling program and the action 
routine. 

The optional action routine should have the form: 
status.wlc.v = ACTION-ROUTINE (string. rt.dx [, user-arg. xx.x]) 

See Section 4.7 for an example of the code to invoke a user action routine. 

2.6.2 STAT Entry Point 

A STAT procedure returns the information you want as binary results. The calling sequence is as 
follows: 

ret-status.wlc.v = LIB$STAT_name (code.rl.r, value.wl.r) 
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code 

A code designating the statistic you want. A separate code is defined for each statistic available; 
the codes are the same for the SHOW and STAT entry points. Codes start at one. 

value 

The value of the returned statistic. 

2.7 Documenting Procedures and Modules 

You must document each procedure carefully so you and others know what the procedure does. In 
most cases, a module contains only one procedure. 

2.7.1 How to Write a Module Description 

You should place a preface containing the following information at the front of each module: 

Title: 

Gives the module name followed by a one-line functional description. 

Version: 

Gives the version and a three-digit edit number. Generally 1-001 is the original version. 

Facility: 

Gives a description of the library facility, such as general utility library (LIB). 

Abstract: 

Gives a short (three to six lines) functional description of the module. 

Environment: 

Lists any special environmental assumptions that the module can make. These include assump¬ 
tions made at both compilation and execution time that could affect either the hardware or 
software environments. 

For execution time, describe situations that the module assumes or optional elements of the 
VAX-11 modular programming standard that your module does not follow. 

If your module follows the Modular Programming Standard, you can usually write, "Runs at any 
access mode — AST reentrant." 

Author: 

Include your name and date you created the module. 

Modified by: 

Include the modification number, name of modifying programmer, modification date, and a list of 
the modifications. 

This concludes the preface. End the preface with a page delimiter. The actual code for the module 
follows the preface, as in the MACRO and BLISS examples shown in Figures 2-3 and 2-4. 

Figure 2—3 shows a sample MACRO module description. 
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Figure 2-3: MACRO Module Description Template 


♦TITLE LIB$TEM PLATE - Sample module 
♦ I DENT /1-001/ 5 File: LIBTEMPLA♦MAR 

? Edit: AAA 1001 

+ + 

FACILITY: General Utility Library 
ABSTRACT: 

This is a sample module* It is used as a templs 
coding MACRO modules for the 0 A X-1 1 Run-Time Lit 

E N 0 IR 0 N M E N T : Runs at any access mode# AST Reentrant 

AUTHOR: Ada A* Augusta# CREATION DATE: 01-JAN-1980 

MODIFIED BY: 

1-001 - Original* AAA 01-JAN-1980 


♦SBTTL DECLARATIONS 
5 

5 LIBRARY MACRO CALLS: 


$SSDEF 


; EXTERNAL DECLARATIONS: 


SS$_ symbols 


♦ DSABL 

♦ EXTRN 

♦ EXTRN 


GBL 5 Force 

LIB$_INUARG 

LIB$SIG_TO_RET 


all external symbols to 
5 Invalid a r Su me nt 
5 Convert signals to re 


MACROS: 


NONE 

EQUATED SYMBOLS: 

NONE 

OWN STORAGE: 

♦PSECT _LIB$DAT A PIC 
NOEX 

NONE 

PSECT DECLARATIONS: 

♦PSECT _LIB$CODE PIC 
EXE * 


USR 
t RD 

# CON > 

# WRT » 

REL # 
LONG 

LCL t 

NOSHR 

USR 
RD # 

* CON * 
NO WRT * 

REL » 
LONG 

LCL * 

SHR » 


Figure 2-4 shows a sample BLISS module description. 


ite for 
• r a r y ♦ 


be declared 
u r n status 


2—18 Designing Modular Procedure Interfaces 






Figure 2-4: BLISS Module Description Template 


‘/.TITLE ' L I B$TEM PLATE - 
MODULE LIB$TEM PLATE ( 

I DENT = '1-001 

) = 

BEGIN 


Sample mo du 1 e ' 

! Sample mod u 1 e 
! File: LIBTEM PLA♦B32 
! Edit: AAA 1001 


+ + 

FACILITY: General Utility Library 


ABSTRACT: 


This is a sample module* It is used as a template for 
codin? BLISS modules for the 0 A X-11 Run-Time Library* 

E N0 IR0NM E N T : Runs at any access mode - AST reentrant 


AUTHOR: Ada A* Augusta# CREATION DATE: 01-Jan-1980 


MODIFIED BY: 


1-001 - Original* AAA 01 -J a n- 19 8 0 


7.SBTTL 'Declarations' 


SNITCHES: 


SNITCHES ADDRESS ING_MODE (EXTERNAL = GENERAL * 
NONEXTERNAL = NORD-RELAT IOE ) 5 


! LINKAGES: 

! 

! NONE 

! 

! TABLE OF CONTENTS: 

! 

FORNARD ROUTINE 

LIB$TEMPLATE ? ! Sample routine 

! 

! INCLUDE FILES: 

I 

LIBRARY 'RTLSTARLE'i ! System symbols# typically from 

! SYS*LIBRARY:STARLET.L32 

REQUIRE 'RTLIN:RTLPSECT'5 ! Define PSECT declarations macros 


MACROS: 


NONE 


(continued on next page) 
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EQUATED SYMBOLS: 


! NONE 

i 

! FIELDS: 

i 

! NONE 

i 

! PSECTS: 

! 

DECLARE-PSECTS (LIB) 5 ! Declare PSECTs for LIB$ facility 

! 

! OWN STORAGE: 

! 

! NONE 

! 

! EXTERNAL REFERENCES: 

i 

EXTERNAL ROUTINE 

LIB$SIG_TO_RET5 ! Convert signals to return status 

EXTERNAL LITERAL ! Condition value symbols 

LIB$_INUARG 5 ! Invalid argument 


2.7.2 How to Write a Procedure Description 

You should place a procedure description at the beginning of each procedure in a module. 

Always list each of the following topics regardless of their actual presence. For example, if a proce¬ 
dure has no implicit inputs, write: 

! Implicit Inputs: 

! NONE 


The procedure description includes the following elements: 

Functional Description: 

The functional description describes a module's purpose and completely documents its interfaces. 

The description should include the basis for any critical algorithms used, including literature 
references, where applicable. It should also explain why a particular algorithm was chosen. 

Calling Sequence: 

A procedure's calling sequence includes: (1) a return status, value parameter, or CALL instruction, 
followed by (2) the procedure name, followed by (3) the parameter list, which is typically a list of 
registers or parameters. In MACRO, each parameter is symbolically defined as the offset relative 
to the argument pointer, AP. 

List the parameters in the order they will be written in a higher-level language. Each parameter 
characteristic should also be included, using the procedure parameter notation described in 
Appendix C. 
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Some examples of calling sequences are: 

ret-status.wlc.v = LIB$GET_INPUT (get-str.wt.dx [.prompt-str.rt.dx [,outlen.ww.r]]) 
string-len.wlu.v = LIB$LEN (string.rt.dx) 

CALL LIB$CRC_TABLE (poly.rlu.r, table.wl.ra) 

Formal Parameters: 

List any explicit input, input-output, or output parameters. Include a qualifying description with 
each parameter. You should list the parameters in the order they are listed in the calling 
sequence. 

Implicit Inputs: 

List any inputs from storage, internal or external to the module, that are not specified in the 
parameter list. Note: usually NONE. See Section 2.3. 

Implicit Outputs: 

List any outputs to internal or external storage that are not specified in the parameter list. 
Completion Status: (or Routine Value:) 

List the success or failure condition value symbols that could be returned as completion codes in 
RO. If your procedure returns a function value other than a condition value in RO, change the 
heading to Routine Value. 

Side Effects: 

Describe any functional side effects not evident from a procedure's calling sequence. This in¬ 
cludes changes in storage allocation, process status, file operations, and possible signaled condi¬ 
tions. In general, you should document anything out of the ordinary that the procedure does to 
the environment. If a side effect modifies local or global storage locations, document it in the 
implicit output description instead. 

Figure 2-5 shows a sample MACRO procedure description. 

Figure 2-5: A Sample MACRO Procedure 

. SBTTL LIB$TEMPLATE - Sample routine 

; + + 

; FUNCTIONAL DESCRIPTION: 

5 This routine is an example for coding procedures 

; in MACRO* It has no computational function* 

5 CALLING SEQUENCE: 

; ret_status*wlc*u = LIB$TEMPLATE (parameter* rl ♦ r) 

; FORMAL PARAMETERS: 

; PARAMETER Lonsfword input parameter 

5 IMPLICIT INPUTS: 

5 NONE 


(continued on next page) 
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IMPLICIT OUTPUTS 


NONE 

COMPLETION STATUS: 

SS$_NORMAL Normal successful completion 

LIB $ _IN U A R G Invalid argument 

SIDE EFFECTS: 

NONE 


♦ENTRY 

L I B$TEMPLATE > A M<I0 > 

5 

Entry point as status 

MOUAB 

G"LIB$SIG_TO_RET» 

(FP) 

5 

Return signals as status* 

TSTB 

( AP) 


5 

Argument present? 

BGTRU 

1$ 


5 

Branch if argument present 

MOUL 

»LIB$_INUARG t RO 


5 

Not invalid a r a u m en t ♦ 

RET 

Z 4 - 



5 

Retur n 

? Come here if 

the argument c o u nt 

is at 

1 

east 1 ♦ 

5 - 

1$: MOUL 

#SS$_NORMAL* RO 


! 

Indicate success 

RET 



5 

End of routi n e 

♦ END 



5 

E nd of mod u1e 


Figure 2-6 shows a sample BLISS procedure description. 

Figure 2-6: A Sample BLISS Procedure 

7. S B T T L 'LIB$TEM PLATE - Sample routine' 

ROUTINE LIB$TEM PLATE ( ! Sample routine 

PARAMETER ! Sample parameter 

) = 

! + + 

! FUNCTIONAL DESCRIPTION: 

! 

! This routine is an example for coding procedures 

! in BLISS* It has no computational function* 

! 

! CALLING SEQUENCE: 

! 

! ret.5tatus*wlc*v = LIB$TEMPLATE (parameter* rl♦ r) 

! 

! FORMAL PARAMETERS: 

I 

! PARAMETER L o n S w o r d input parameter 

! 

! IMPLICIT INPUTS: 

j 

! NONE 

i 

! IMPLICIT OUTPUTS: 

! 

! NONE 

(continued on next page) 
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COMPLETION STATUS: 

SS$_NQRMAL Normal successful completion 

LIB$_INUARG Invalid argument 

SIDE EFFECTS: 

NONE 

BEGIN 

BUILTIN 

ACTUALCOUNT5 ! Sample builtin 

MAP 

PARAMETER : BLOCK C 4 » BYTE]5 ! Sample MAP declaration 

LOCAL 

LOCAL-UARIABLE i ! Sample local declaration 

ENABLE 

LIB$SIG_TO_RET? ! Sample enable declaration 

IF (ACTUALCOUNT () LSSU 1) THEN RETURN (LIB$_INUARG)5 
RETURN <SS$_NORMAL)5 


END 5 

! End 

o f 

routi ne 

END 

! End 

of 

m o d u 1 e 

ELUDOM 
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Chapter 3 
Using Storage 


This chapter describes the types of storage available on VAX/VMS. It also tells you how to choose the 
type of storage you need for your program and allocate the type of storage you have chosen. 


3.1 Types of Storage 

There are three types of storage: static, stack, and heap. The three forms of storage differ in the 
method and duration of allocation. 

3-1.1 Static Storage 

The VAX-11 Linker allocates statically storage in one place for the duration of the program's execu¬ 
tion. The storage's initial contents are specified in the source program. On calls to a procedure after 
initialization, the static storage has the same allocation and the contents left from the previous call. 

The following forms of static storage are available in the indicated languages: 

• MACRO 

These statements allocate or allocate and initialize the static storage amount indicated: 


Allocate 

Amount 

Allocate and 
Initialize (to 10) 

.BLKB 

1 Byte 

.BYTE 10 

.BLKW 

1 Word 

.WORD 10 

.BLKL 

1 Longword 

.LONG 10 

.BLKQ 

1 Quadword 

.QUAD 10 

.BLKO 

1 Octaword 

.OCTA 10 


• BLISS 

OWN Storage 
GLOBAL Storage 

In the following BLISS example, A is initialized to 0 and B to 10. 


OMN 

A: LONG t 

B: LONG INITIAL(10)5 
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• BASIC 

All COMMON and MAP data storage is statically allocated. 


• FORTRAN 

All FORTRAN data storage is statically allocated. It can be declared in two ways: 


- As local variables or arrays 

- As COMMON storage 


Static storage can be initialized using the DATA statement. 

In the following FORTRAN procedure, variables A, B, C, FUNC, array D, and string E are all 
statically allocated. Furthermore, variable A is initialized to 10 at compile time, while other 
variables are initialized to 0. X, Y, and Z are not statically allocated: 

FUNCTION FUNC( X > Y *Z ) 

INTEGER*^ A »B >D ( 100) 

DATA A/10/ 

CHARACTER*10 E 
CHARACTER*( ) X 


* 

FUNC 


C 


RETURN 

END 

Note that variable A is not reinitialized to 10 on subsequent calls to FUNC. Instead, the value of A 
and all other statically allocated variables retain the values left from the previous call. The SAVE 
statement must be used to ensure value retention across calls. 

• PASCAL 

All program or module level storage is statically allocated. 

3.1.2 Stack Storage 

A procedure allocates stack storage on the process stack at run time. Stack storage is allocated 
dynamically, as the procedure needs it. It is automatically deallocated when the procedure returns 
control to the calling program. 

• MACRO 

Stack storage is allocated by decrementing the stack pointer (SP) by the number of bytes (n) of 
storage required: 

SUBL2 #<r. + 3>/4 *SP 
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• BLISS 


Stack storage can be allocated as follows: 

STACK LOCAL A: LONG 5 

• BASIC 

Local variables declared in a BASIC program (except virtual arrays and variables in COMMON or 
MAP) are allocated on the stack. 

• FORTRAN 

Stack storage cannot be allocated by a FORTRAN program. 

• PASCAL 

Stack storage is allocated automatically for all PROCEDURE and FUNCTION local variables. 

3.1.3 Heap Storage 

Dynamically allocated heap storage is allocated at run time from a process-wide pool, as the proce¬ 
dure activation needs it. Heap storage is allocated by calling LIB$GET_VM or the system service 
SEXPREG. Heap storage is deallocated — that is, returned to the process-wide pool — by calling 
LIB$FREE_VM. The system service SCNTREG cannot be used to deallocate heap storage. (See Section 
4.6.) 

• MACRO 

Heap storage can be allocated with a call to LIB$GET_VM. (See the VAX-11 Run-Time Library 
Reference Manual and User's Guide.) 

• BLISS 

Heap storage can be allocated as follows: 

EXTERNAL PROCEDURE 

LIB$GET_VM: ADDRESSING-MODE (GENERAL)! 

IF LIB$GET_UM (UPLIT (100) » ADR) 

THEN 

success > ADR set to address allocated 


• BASIC 

Heap storage can be allocated, but it must then be passed BY REF to another procedure as an array 
parameter. BASIC dynamic strings automatically use heap storage. 

• FORTRAN 

Heap storage can be allocated, but it must then be passed to another procedure as an array 
parameter. (See the VAX-11 Run-Time Library User's Guide.) 

• PASCAL 

Heap storage can be allocated by calling NEW and deallocated by calling DISPOSE. 

Figure 3-1 shows how the different types of storage are used. 
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Figure 3-1: Use of Storage Types 






3.1.4 Storage Use Summary 

Table 3-1 summarizes storage available to the programmer in various language procedures. 

Table 3-1: Summary of Storage Use by Language 


Storage Type 

Language 

Static 

Stack 

Heap 

MACRO 

Block storage 

Decrementing stack 
pointer 

By calling LIB$GET_VM 

BUSS 

OWN and GLOBAL 

STACK LOCAL 

By calling LIB$GET_VM 

BASIC 

All COMMON and 
MAP data storage 

Local variables 

Dynamic strings 

FORTRAN 

All data storage 

Not applicable 

By calling LIB$GET_VM 

PASCAL 

All program or 
module level storage 

PROCEDURE and 
FUNCTION local 

By calling NEW 


3.2 Choosing a Storage Type 

A procedure activation combines procedure-implementing instructions and the stack frame storage 
allocated when the procedure is called and deallocated when the procedure returns. Two procedure 
activations can exist at the same time if: 

• The procedure is called by an AST-level routine while it is executing (AST-reentrant). 

• The procedure is called by a condition handler while it is executing (reentrant). 

• The procedure is called by itself or by another procedure that it has called (recursive). 

If a procedure's results must be saved for a subsequent activation, the procedure must use static 
storage or provide a mechanism for the caller to retain storage to access those results. 

If none of the results of a procedure activation need be retained for subsequent activations, the 
procedure can use static, stack, or heap storage. 

Stack storage is always recommended. It is easily allocated, and it performs well in a paging system 
such as VAX/VMS. 

Heap storage allocation is slower than stack storage, and it requires explicit deallocation. It is recom¬ 
mended for use instead of stack storage when a variable or large amounts of information must be 
retained after your procedure returns to its caller. 

Avoid static storage wherever possible. It can cause unwanted side effects if used for implicit parame¬ 
ters (see Section 2.4.2), and when used, it is difficult to make your procedure reentrant or AST- 
reentrant (see Chapter 6). 
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3.3 Using Static Storage 

Three classes of procedures use static storage: 

• Process-wide resource-allocating procedures (see Section 4.4) 

• Non-resource-allocating procedures that retain information from previous activations in order to 
shorten the explicit parameter list (see Section 3.3.1 through 3.3.3) 

• Procedures that do not make use of retained information from previous activations (see Section 
3.3.4) 

When you cannot avoid using static storage, you can maintain modularity by using one of the 
following four techniques. 

3.3.1 Allocating Process-Wide Identifiers 

Your procedure allocates heap storage and returns the address of the allocated storage as a process¬ 
wide identifier to the calling program. 

Each set of related calls uses the same identifier, while each set of unrelated calls uses different 
identifiers. 

You must make sure that the modular procedure rather than its caller allocates and deallocates the 
identifier values. To avoid using static storage, this identifier can be the actual address of heap 
storage. 

Format 

ret-status.wlc.v = LIB$INIT_BLOCK (handle.wl.r) 

Example (BLISS) 

ROUTINE LIB$INIT_BLOCK(HANDLE)= 

BEGIN 

EXTERNAL ROUTINE LIB$GET_UM 5 

LITERAL BLOCKSIZE = 16? ! Block size in bytes 

RETURN (LIB$GET_UM (1 REF (BLOCKSIZE) > ♦HANDLE) ) 5 
END ; 

Example (FORTRAN) 

FUNCTION LIB$INIT_BLOCK (HANDLE) 

INTEGER*^ LIB$INIT_BLOCK t HANDLE t LIB$GET_UM 
LIB$INIT_BLOCK = LIB$GET_VM <1G, HANDLE) 

RETURN 

END 


3.3.2 Passing the Address of Storage 

The calling program can allocate a (static or dynamic) storage area and pass its address. In the 
following example, the random number generator from the math library (MTH$RANDOM) uses this 
method to produce the seed. 

Format 

ran_num.wf.v = MTH$RANDOM (seed.mlu.r) 
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Example (MACRO) 


S E E D = 4 5 formal arg list offset 

♦ENTRY MTH$RANDOM* 0 5 no registers saved* clear IV 


If this were to be placed as an inline expansion* 
EMUL SEED* # 6 9 0 G 9 * # 1 * R 0 should replace the next two 
instructions* This would prevent possible 
integer overflow trapping 


MULL2 #69069* @ S E E D ( A P ) ? Update seed with multiplier 

INCL @SEED(A P) 5 Increment seed to protect 

5 against strange seeds 

5 + 

? The next instructions convert the seed from unsigned integer 
5 to floating-point in the range 0*0 to 1*0 exclusive* 


EXTZU #8* #24* @ S E E D ( A P ) * R0 5 Get the most significant bit 

? of the seed in the range 
5 0 to (2*24)- 1♦ 

C 0 T L F R 0 »R 0 5 Convert to floating without 

5 rounding* The result is 
5 positive and in the range 
? 0*0 to (2*0*24)-1*0 

+ 

If this were to be placed as an inline expansion* then 
M U L F #''/< 0 0 0 0 3 4 8 0 * R 0 could replace the next two inst ructio n s ♦ 


B E Q L 10$ 5 If zero* already correct. 

SUB W #24@7 * RO 5 DIUF # A F2.0*24 

5 The result is now in the 
? range 0*0 to 1*0 exclusive* 

10$: RET 
♦ END 


The following FORTRAN calling program allocates the needed static storage and passes it to 
MTH$RANDOM: 

INTEGER*4 RAN_SEED 

REAL*4 RAN_0AL * MTH$RANDOM 

RAN-OAL = MTH$RANDOM (RAN_SEED) 


RAN_VAL is set to a random floating-point value. 

3.3.3 Pushing Down the Contents of Static Storage 

In this method, the interface between the calling program and the called procedure consists of a 
series of calls. If any implicit parameters are active from previous activations, the first call saves their 
contents on a push-down stack in heap storage, not on the process stack. The last call restores the 
saved implicit parameters. In this way, static storage is made available to your sequence of proce¬ 
dures, so they can pass implicit inputs from one to another. 
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To use this technique, include in the module an initial za^on procedure that, among other things, 
automatically pushes the information stored in static storage onto a simulated software stack 
maintained in heap storage. This information will rema a there during current and future procedure 
activations. Then, write a termination procedure that automatically pops information back into static 
storage. 

The calling program calls the initialization and termination procedures at the beginning and ending of 
the sequence of calls to your module. The calling program must also establish a condition handler 
that will call the termination procedure (so the data will be popped back into static storage) in case 
the stack must be unwound. 

For example, BASIC and FORTRAN language-support procedures push down the contents of static 
storage for the current I/O statement whenever an I/O statement is initiated. Thus, I/O statements 
consist of a sequence of calls: 

1. I/O statement initialization procedure 

This procedure sets up the I/O system by initializing its static storage for the specific I/O 
requested, and flags the logical unit to be active. If the specified unit has not already been 
explicitly opened, a default open can be performed, with buffers and control blocks dynamically 
allocated. If an I/O statement is already being processed, the static storage used by that I/O 
statement is pushed down. 

2. Data element transmission procedure(s) 

Each data element transmission procedure copies one data element from/to the user program 
to/from the I/O buffer for the logical unit. The logical unit is an implicit input. 

3. I/O statement termination procedure 

This procedure completes the current I/O statement. The logical unit number is an implicit input. 
If an I/O statement had been pushed down, it is now popped back into static storage. This 
restores it as the current I/O statement. 


For example, the BASIC statement: 


PRINT #2 » 11 »IFUNC< SI) ,B 


is compiled as: 


MOVL -(SP) 

CALLS #1> G"BAS$PRINT 

PUSHL IX(Rll) 

CALLS G"BAS$OUT_I_V_C 

PUSHAL J7. ( R 1 1 ) 

CALLS #1 , G-IFUNC 
PUSHL RO 

CALLS #1> G"BAS$OUT_I_V_C 
MOVF B(R11), -(SP) 

CALLS *1> G‘‘BAS$OUT_F_V_B 
CALLS #0* G"BAS$I0_END 


Unit Numbe r 

Initialize PRINT 

sequential unformatted 

Value of I "L 

Transmit integer 

Address of J 1 

Call function IFUNC 

Push f un c t i o n u a 1u e 

T ransinit b v i m mediate u a 1 u e 

Value of B 

Transmit floating 

End of the I/O list 


If function IFUNC performed I/O, the PRINT statement would be pushed down and popped back 
before control returns from IFUNC. 
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3.3.4 Using Static Storage for Results that Are Not Retained 


You can use static storage in a modular way if your procedure uses static storage and does not need to 
retain values after returning control to its caller. To do this write each variable before reading it. 

In FORTRAN, this is done by assigning an expression to each variable before using that variable in 
another expression. For example, the following FORTRAN code is modular even though static storage 
is used exclusively: 


FUNCTION (A) 
INTEGER D 
D = A 
G = D +A 


In this example, the static variables D and G are initialized to expressions consisting solely of 
variables passed as explicit input parameters. 

3.4 Using Stack Storage 

You can use stack storage to maintain modularity and avoid the special considerations necessary for 
static storage. If your procedures are written in MACRO, BLISS, BASIC, or PASCAL, you should use 
only stack storage when your procedure does not need to retain values from its previous activations. 
Note that stack storage is not available in FORTRAN. 

Specific advantages of using stack storage are: 

• Data is automatically hidden from source code outside the procedure. 

• Program performance is improved since the same pages of memory are used by many different 
procedures. 

• Procedures are automatically AST-reentrant. 

• Unintended interaction between successive activations of the same procedure is avoided. 

• Stack storage is automatically deallocated on procedure return. 

3.4.1 Using Stack Storage in MACRO 

In MACRO, allocate stack storage by subtracting the number of bytes required from the stack pointer 
(SP) provided on entry. For efficient operation, you should allocate stack space in multiples of four 
bytes to keep the stack aligned on a longword boundary. The CALLS and CALLG instructions auto¬ 
matically align the stack at procedure entry time. 

The following MACRO procedure concatenates two source strings and returns the result as a single 
fixed-length string. No restrictions are placed on the overlapping of source and destination strings; 
therefore, a temporary stack storage technique is used. 

In the example, these steps occur: 

1. Add the source lengths to the stack pointer SP. 

2. Copy first string to stack. 

3. Copy second string to stack. 

4. Copy stack to result. 
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The calling sequence is: 

CALL LIB-CONC (result.wt.ds, srcl.rt.dx, src2.rt.dx) 


RESULT = 4 
SRC 1 = 8 

SRC2 = 12 


5 A r 3 list offset 
5 A r S list offset 
? ArS list offset 


for result 
for sou reel 
for source2 


♦ ENTRY 


LIB.CONC 

MOOZWL 

MOOZWL 

ADDL 

SUBL 

MOOQ 

M00C3 

MOOQ 

M00C3 

MOOQ 

M0UC5 

RET 


, M< R2 *R3 >R4 >R5 * R 6 > 

@ S R C 1 ( A P ) ? RG 5 RG = length of sou reel in bytes 

@ S R C 2(A P) t R 0 5 R 0 = length of s o u r c e 2 in bytes 

RO * RG ? RG = total length 

RG * SP 5 Allocate space for SRC1 and SRC2 

@SRC 1 (A P) * RO ? RO <15:0 > = lem R1 = adr of SRC1 

RO t (R1) * (SP) ? Move SRC1 to stack# R3 now = 1 byte 

5 b e y ond destination 

@SRC2(AP) t RO 5 RO <15s0> = lent R1 = adr of SRC2 
RO t (Rl)» (R3) 5 Move SRC2 to stack 

@RESULT(AP)» RO ? RO = len of result » R1 = adr of result 
RG t ( SP ) f # '■ A ' ' * RO t ( R 1 ) 5 copy temporary back to result 
5 Return > deallocating stack storage 


3,4.2 Using Stack Storage in BLISS 

When using stack storage in BLISS, define each variable in the innermost nested block. This keeps the 
amount of code that affects the variable to a minimum, making it easier to understand and maintain 
the procedure. 

The following BLISS example computes the area of a rectangle, using stack storage to hold the result: 


ROUTINE COMPUTE.AREA (HEIGHT * WIDTH) = 

BEGIN 

STACK LOCAL AREA i 
AREA = ♦HEIGHT ♦WIDTH? 

RETURN *AREA? 

END ; 

3.4.3 Using Stack Storage in BASIC 

All variables, strings, and arrays are allocated in the stack in BASIC, except for COMMON or MAP. 
Thus, it is very easy to use stack storage in BASIC. 

The following BASIC example computes the area of a rectangle, using stack storage to hold the result: 


100 FUNCTION INTEGER COMPUTE_AREA (HEIGHT’/. * WIDTH'/) 
200 AREA/ = HEIGHT/ WIDTH/ 

300 COMPUTE-AREA = AREA/ 

400 FUNCTIONEND 


3.4.4 Using Stack Storage in PASCAL 

All local variables and arrays of PROCEDURES and FUNCTIONS are allocated in the stack in 
PASCAL. Thus, it is very easy to use stack storage in PASCAL. 
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The following PASCAL example computes the area of a rectangle, using stack storage to hold the 
result: 


FUNCTION COMPUTE_AREA (HEIGHT : INTEGER ? 

WIDTH : INTEGER) : INTEGER 5 

VAR AREA : INTEGER 5 
BEGIN 

AREA := HEIGHT WIDTH? 

COMPUTE_AREA := AREA 5 
END ; 


3.5 Using Heap Storage 

You can use heap storage to dynamically allocate arbitrary amounts of storage. Heap storage is useful 
for retaining variable amounts of information from one procedure activation to another. 

If your procedure does not explicitly deallocate the heap storage by calling LIB$FREE_VM before 
returning to its caller, your procedure must do one of the following: 

• Retain the address of the heap storage in static storage so that the storage can be deallocated later. 

• Return the address (and also the responsibility for deallocation) to the caller. 

This lets you use or deallocate the storage on a later activation. (See Section 2.5.) 

3.5.1 Allocating Heap Storage in BLISS 

This example allocates a buffer from heap storage: 


STRING-PTR is OWN storage which holds a pointer to 
a dynamically allocated buffer of 80 bytes* 


own string_ptr; 

LIB$GET_VM ( 7. R E F ( 8 0 ) * STRING-PTR)? 


The following BLISS example illustrates the use of heap storage to pass information between calls 
without using static storage. Instead, the responsibility for deallocation of heap storage belongs to the 
calling program. 

MODULE DEMO ( IDENT = '1-015' > = 

BEGIN 

SWITCHES ADDRESSING-MODE (EXTERNAL = GENERAL * 

NONEXTERNAL = WORD-RELATIVE) 5 
FORWARD ROUTINE SAMPLE-ROUTINE t FREE_HEAP_STORAGE ? 

LIBRARY 'SYS$LIBRARY:STARLET'? ! System definitions 

EXTERNAL ROUTINE 

LIB$GET_VM> ! Allocate heap storage 

LIB$FREE_VM» ! Deallocate heap storage 

LIB$MATCH_C0ND 5 ! Match condition codes 


(continued on next page) 
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GLOBAL ROUTINE SAMPLE_ROUTINE = 

BEGIN 

LOCAL 

A_LEN_AND_POINTER : VECTOR [23 VOLATILE * ! length and address of 

! 1st heap storage area 
! to be allocated 

B_LEN_AND_POINTER : VECTOR [23 VOLATILE 5 ! length and address of 

! 2nd heap storage area 
! to be allocated 

! + 

! Enable a handler to free the heap storage in case an error in a 
! routine we call causes an UNWIND* 


ENABLE 

FREE_HEAP_STORAGE (A_LEN_AND_POINTER t B_LEN_AND_POINTER) 5 


Allocate the heap storage we will need* 

A_LEN_AND_P0 INTER [03 = 2000 5 ! Number of bytes desired 

LIB$GET_VM ( A_LEN_AND_POINTER [03» A_LEN_AND_POINTER [13 ) 5 


B_LEN_AND_POINTER [03 = 5000 ; 

LIB$GET_VM ( B_LEN_AND_POINTER [03 


! Number of bytes desired 
B_LEN_AND_POINTER [13 ) 5 


We now proceed with our 
is in A_LEN_AND_POINTER 
A_LEN_AND_POINTER [13* 
is in B_LEN_AND_POINTER 
B_LEN_AND_POINTER [13* 


computations* The length of the 1st buffer 
[03 and its starting address is in 
Similarly * the length of the 2nd buffer is 
[03 and its address is in 


When processing completes normally ♦ free the heap storage we were 
using* 


+ 

Free the storage* 


LIB$FREE_VM (A_LEN_AND_POINTER 
LIB$FREE_VM (B_LEN_AND_POINTER 
RETURN <SS$_NORMAL)5 ! 
END 5 ! 


[03 * A_LEN_AND_POINTER 
[03 * B_LEN_AND_POINTER 
indicate success 
end of SAMPLE.ROUTINE 


[13) ; 

[13) ; 


ROUTINE FREE_HEAP_STORAGE ( 

SIG , 

MECH , 

ENBL 

) = 

! + + 

! FUNCTION: 

! 

! If we are unwinding > free the heap storage we may h a u e 

! allocated* The length and addresses of these areas are passed in 
! pairs of longwords (zeroth containing length and 1st containing 
! starting address) 

! The address of -the zeroth longword in each pair is passed in the 
! ENABLE vector* 

(continued on next page) 


Free local HEAP_STORAGE 
Signal vector 
Mechanism vector 
Enable vector 
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FORMAL PARAMETERS: 

SIG♦r1♦a A counted vector of parameters to 

LIB$SIGNAL/STOP 

MECH♦ r1♦a A counted vector of info from CHF 

E N BL♦ r a♦a A counted vector of ENABLE argument addresses* 

COMPLETION CODES: 

Always S S $ _ R E SIG N A L f which is ignored when unwindin S♦ 

SIDE EFFECTS: 

Frees all of the heap storage passed as enable arguments* 


BEGIN 

MAP 

SIG : REF VECTOR t 
MECH : REF VECTOR t 
ENBL : REF VECTOR 5 


Only free storage if this is the UNWIND condition* 

IF ( NOT (LIB$MATCH_COND (SIG Lilt 7, REF (SS$_UNWIND) ) ) ) 
THEN RETURN (SS$_RESIGNAL)5 


+ 

Go through the enable arguments » freeing them* 


I NCR ARG_NO FROM 1 TO *ENBL [03 DO 
BEGIN 
LOCAL 

LENGTH t 
ADDR 3 

LENGTH = ♦♦ENBL C*ARG_N03 5 

ADDR = ♦(♦ENBL C*ARG_N03 + 4) 3 

IF ( ♦ LENGTH NEQ 0 AND *ADDR NEQ 0) 
THEN 

LIB$FREE_VM ( LENGTH t ADDR >3 

END 3 


! for all arguments 


! Length of area 
! Address of area 
If space really allocated » 

then free space indicated* 


RETURN (SS$_RESIGNAL)3 
END 3 

END 

ELUDOM 


! end of FREE_HEAP_STORAGE 
! end of module DEMO 
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Chapter 4 

Coding Modular Procedures 


This chapter describes how to code modular procedures and make existing procedures modular in 
MACRO, BLISS, BASIC, FORTRAN, and PASCAL. The chapter covers these topics: 

• Structured programming recommendations 

• Coding rules and recommendations 

• Procedure initialization 

• Resource allocation 

• Use of system services 

• Optional user action routines 

Chapter 5 explains signaling and condition handling. 

If you want your procedure to be AST-reentrant, refer to Chapter 6 for additional coding techniques. 


4.1 Structured Programming 

To construct a well-designed set of modular procedures, you should organize your task into concep¬ 
tual layers. Begin writing your programs starting with the outermost abstract form. Then move inward 
toward successively greater detail. 

Before coding individual procedures, consider how they might be grouped into modules. If you have 
a number of procedures that access common data or control blocks, try to organize them into 
separate levels, with each level having responsibility for different parts of the data structure. 
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4.1.1 Levels of Abstraction 


If you are writing a large number of related procedures that call one another or access common data 
blocks, make the relationship among them as clear as possible. You can do this by organizing 
procedures to minimize interaction with each other and with the data structure: 

• Organize procedures into levels of abstraction. 

• Make sure each level needs to make calls only to the next level. 

• Restrict read/write access at each level to nonoverlapping subsets of the data. 

Figure 4—1 shows the BASIC and FORTRAN record I/O statement processing procedures. These are 
implemented in the following three levels: 

• User program interface (UPI) 

• User program data formatting (UDF) 

• Record processing and VAX—11 RMS interface (REC) 


Figure 4-1: Levels of Abstraction 



All calls are made in one direction: to the next innermost level. Procedures at different levels should 
be in different modules. 
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4.1.2 Grouping Procedures 


Although generally each module should contain a single procedure, you may sometimes find it 
convenient to place more than one procedure in a single module if a procedure is called only by 
other procedures in that module. Grouping procedures in a module is also recommended if two or 
more procedures either: 

• Share the same static storage 

• Have similar calling sequences, perform similar functions, and share a significant amount of 
common code 

The VAX-11 Linker always brings the entire module containing a called procedure into the image if 
any of its entry points are referenced. Thus, placing each procedure in a separate module reduces 
image size. It also allows more flexibility in using a procedure library, because you can supply your 
own version of one procedure while using other procedures from the library. If many procedures have 
been grouped in a single module, the linker must link all of them or none. 

Figure 4-2 shows possible groupings of procedures. 


4.2 Coding Rules and Recommendations 

Coding rules and recommendations help maintain modularity and produce consistent, readable soft¬ 
ware. You should choose simple rules. DIGITAL uses the following coding rules and recommenda¬ 
tions for all modular procedures. These rules are drawn from the Modular Programming Standard 
(Appendix A). You must follow the sections marked "standard." You may choose to follow sections 
marked "recommended" for procedures to be uniform and, therefore, easier to learn and remember. 


4.2.1 Relocatable Modules (Standard) 

Most modules are, by default, relocatable during linking. The compiler or translator makes it appear 
to the linker that each module starts at location 0. The linker relocates each module to make it fit with 
the other modules being linked to form an executable image. A nonrelocatable module is a module 
with absolute storage allocation. It does not adhere to the modular standard since each absolute 
assignment might conflict with a similar assignment in another module. 


4.2.2 File Names (Recommended) and Module Names (Standard) 

File names are derived from procedure names. If a module contains a single procedure, the file name 
consists of the first nine characters of the procedure name without the dollar signs and underscores. If 
the module contains more than one procedure, a more general file name is used, composed of the 
facility prefix and the first noun common to all procedure names in the module. File name extensions 
are the standard default extensions for the source language. 

Module names are identical to file names except for the dollar sign (DIGITAL—supplied) or underscore 
(user-supplied) inserted after the facility code. Module names do not have extensions. 

For example, the MTH$EXP procedure is contained in module MTH$EXP and the file MTHEXP.MAR. 
The LIB$GET_VM and LIB$FREE_VM procedures are contained in the module LIB$VM and the file 
LIBVM.B32. 
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Figure 4-2: Possible Procedure Groupings 
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4.2.3 PSECT Names (Standard) 

The code and data sections of a customer library procedure have two separate program sections 
(PSECTs), named _fac_CODE and _fac_DATA, where fac is the facility name. DIGITAL uses 
_fac$CODE and _fac$DATA as PSECT names. 

Position-independent constant data is in the PSECT named _fac_CODE (_fac$CODE for DIGITAL) to 
shorten the references. For example, _LIB$CODE and _LIB$DATA are the only two PSECT names 
used by LIB$ procedures. The collating sequence for leading underscores causes the linker to place 
all library procedures after the user program in the executable image. Therefore, a library procedure 
will not be placed between two user modules. This prevents it from adversely affecting byte or word 
displacement addressing that the user program contains. Declare PSECTs as follows: 

• MACRO 

♦ PSECT _ fac _CODE PIC ,USR * CON , REL,LCL ,SHR , E X E,RD * NOWRT 

♦ PSECT _ f a c _ DAT A PIC ,USR ,CON ,REL>LCL tNOSHR ,NOEXE ,RD ,WRT 


• BUSS 


PSECT 

CODE = -f ac-CODE (READ , NOWRITE, EXECUTE , SHARE , PIC* 
CONCATENATE , ADDRESS ING_MODE (WORD-RELATIVE) ) , 

PLIT = _fac_CODE (READ , NOWRITE, EXECUTE, SHARE, PIC, 
CONCATENATE, ADDRESS ING-MODE (WORD-RELATIVE)), 

OWN = _fac_DATA (READ, WRITE, NOEXECUTE, NOSHARE, PIC, 
CONCATENATE, ADDRESSING-MODE (LONG-RELATIVE)), 

GLOBAL = _fac_DATA (READ, WRITE, NOEXECUTE, NOSHARE, PIC, 
CONCATENATE, ADDRESSING-MODE (LONG-RELATIVE) ) 5 


• BASIC and FORTRAN 

You do not have control over PSECT names, except named program COMMON. Note, however, 
that program COMMON replaces the PSECT attribute CONCATENATE with OVERLAY. Therefore, 
storage that you allocate using COMMON might overlay that allocated by a procedure written by 
someone else. Such a conflict between the two modules would go undetected. Therefore, use of 
COMMON violates the modular programming standard. 

• PASCAL 


You do not have control over PSECT names. 

4.2.4 Parameter Definition Files (Recommended) 

In some programs, it may be necessary to make identical parameter declarations in several modules. 
In MACRO, BLISS, BASIC, FORTRAN, and PASCAL, such declarations are centralized in one place. 

• MACRO 

An auxiliary source file or macro library can be specified in the command line. 

• BUSS 

Your source program can contain a REQUIRE or LIBRARY declaration that specifies a file to be 
included at the point of the declaration. 
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• BASIC 


An auxiliary source file can be appended (using the BASIC APPEND command) to your main source 
program prior to compilation. If you use this method, make sure that the line numbers in the 
appended file do not duplicate any line numbers in the source program. If they do, the lines from 
the appended file will replace the lines in the source program. 

• FORTRAN 

The INCLUDE statement specifies a file to be included at the point of the statement. 

• PASCAL 

The %INCLUDE directive specifies a file to be included at the point of the directive. 

You should use this technique to declare the symbolic offsets in a control block accessed from 
several modules. 

4.2.5 Symbols in Place of Numbers (Recommended) 

Use symbols, not numbers, as much as possible. This makes the program clearer, since symbols are 
mnemonic, and provides more information for cross-reference listings. 

• MACRO 

The use of local numeric labels is encouraged within a logical unit of code that fits on a single 
listing page. 

• BLISS 

The defined transportable symbols are used for hardware defined-quantities. For example, the size 
of a general value is %BPVAL (bits per value) instead of 32, and the length of a general value is 
%UPVAL (addressable units per value) instead of 4. 

4.2.6 Line Length (Recommended) 

The maximum line length for source code in each language follows. Line lengths are shown for actual 
source code (not including sequence numbers). 


Language 

Maximum Line Length 

MACRO 

80 

BLISS 

124 

BASIC 

512 

COBOL 

74 (ANSI format) 


125 (Terminal format) 

FORTRAN 

72 

PASCAL 

(no limit) 


4.2.7 Uppercase and Lowercase (Recommended) 

Uppercase should be used for all source code except comments. Uppercase and lowercase should be 
used for all comments. Comments that are complete sentences should start with a capital letter and 
end with a period. 
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4.2.8 Optional Spaces (Recommended) 

A single space follows a comma and precedes and follows an equal sign ( = ). A single space must 
precede a left parentheses or a left square bracket (except in MACRO), but not a left angle bracket. A 
space also follows an exclamation mark or semicolon to separate a comment from the source code. 
Plus and minus symbols ( + and -) are surrounded by spaces in expressions. 

4.2.9 Block Comments (Recommended) 

You can comment on blocks of statements by writing one or more lines preceding the block. Com¬ 
ments start in column 1, independent of the indentation of the code. The first comment line contains 
a single plus sign ( + ); the last comment line contains a single minus sign (—). Block comments do not 
need to be set off by additional blank lines since the two flag lines (starting with + and -) serve that 
purpose. Comment delimiters are followed by one space, except when followed by the first + and 
the last —, as shown in this MACRO example: 

M0VL RO * TABLE 5 Store current char* ad r ♦ in 

? Code table 
5 + 

5 This is a b 1 o c K comment in M A C R□ ♦ 

5 - 

10$: M00L TABLE* R0 ! RO = current character 

5 address 

4.2.10 Branch and Jump Instructions (Recommended) 

• MACRO 

When branch and jump instruction refer to labels, the labels should be located at a later point in 
the program listing (except for loops and first-time initialization). Thus, when you encounter a 
label, you have already read all of the code that could transfer to the label. 

• Other languages 

GO TO instructions should follow similar conventions. 


4.3 Initializing Modular Procedures 

Some modular procedures must initialize themselves before they can execute correctly. Examples of 
initialization are: 

• Storing in static storage a value that can only be determined at run time 

• Declaring an exit handler using the $DCLEXH system service 

• Allocating a process-wide resource once 

• Opening a process-permanent file the first time, in case a logical name was used and the file was 
not already opened 

Initialization of dynamically allocated stack and heap data simply involves writing the data after each 
allocation before reading it. 
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You must perform initialization carefully to maintain modularity: 

• Initialization must not affect the calling program. Therefore, you cannot initialize by providing an 
entry point that must be called before any other entry point is called. This would force the calling 
program to provide an initialization entry point to its caller, and so forth. Also, you would have to 
rewrite your calling programs if you needed to substitute a procedure with an initialization call for 
one without an initialization call. 

• If your procedure uses LIB$INITIALIZE, you must preserve a modular environment that does not 
conflict with the environment set by any other procedure using LIB$INITIALIZE. (See the VAX-11 
Run-Time Library Reference Manual.) 

There are several ways to initialize a procedure: 

• Initialize at compile or link time. 

• Call LIB$INITIALIZE before you call the main program. 

• Set a first time flag at run time. 

• Initialize storage each time it is allocated at run time. 

• Initialize storage each time a procedure is called at run time. 

The use of each method is explained in the following sections. Figure 4-3 summarizes these 

methods. 


Figure 4-3: Methods of Initializing 


Initialization 

Needed 

Method 

Initialize at 
Compile/Link Time 

Call LIBSINITIALIZE 
Before Main 
Program 
(At Run Time) 

Set a First 
Time Flag 
(At Run Time) 

Initialize Each 
Time It Is 
Allocated 
(At Run Time) 

Initialize Each 
Time Procedure 

Is Called 
(At Run Time) 

Of Static Storage: 

• 

• 

• 



Of Stack Storage: 





• 

Of Heap Storage: 




• 


To Allocate 

Resources: 


• 

• 



To Set Up 
$EXIT Handler: 


• 

• 



To Open a Process- 
Permanent File: 


• 

• 



To Set Up a Handler 
Before the Main 
Program: 


• 
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4.3.1 Initializing Storage Areas 

For a procedure to produce predictable results, all statically and dynamically allocated areas must be 
initialized to known values before they are read. 
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The initialization of static storage need happen only one time in each image activation. Thus, the 
known values can be specified: 

• At compile time by using a data initializing statement 

• At link time by using a data allocation statement 

• At run time on the first call to the procedure 

4.3.2 Initializing Static Storage 

If your procedure has static storage, you usually initialize it to zero. You can do this: (1) explicitly 
with a data initialization statement or (2) implicitly with the linker. 

To save disk space, the linker does not include in the .EXE file data pages initialized to zero. In 
addition, I/O is eliminated, since data pages are allocated upon your first access after the image is 
activated. 

The following examples show initialization of a longword, DAT, in static storage at compile or link 
time. 


Statement 


Initialized Value 


MACRO: 


DAT: .BLKB 1 0 

DAT: LONG 0 0 

DAT: LONG 100 100 

BLISS: 

OWN DAT; 0 

OWN DAT INITIAL(O); 0 

OWN DAT INITIAL(IOO); 100 

FORTRAN: 

INTEGERS DAT 0 

DATA DAT /0/ 0 

DATA DAT 7100/ 100 


Note 

BASIC does not permit static storage within a module, only common static storage. 

PASCAL has static storage at module level. EHowever, you cannot initialize it at com¬ 
pile time. 

4.3.3 Testing and Setting a First-Time Flag 

Occasionally, your procedure requires initialization that can be performed only at run time, the first 
time your procedure is called. Examples are: 

• Initializing static storage to a value that can only be determined at run time 

• Establishing an EXIT handler 

• Allocating a resource 

• Opening a process-permanent file 
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To do first-time initialization, your procedure tests and then sets to one a statically allocated first-time 
flag each time it is called. This flag is initialized to zero at compile or link time. Setting and testing the 
flag with the VAX instruction BBSS (Branch on Bit Set and Set) insures that initialization is executed 
exactly once. 

However, if the procedure is to be AST-reentrant, it must follow these steps: 

1. Test the first-time flag. 

2. If it is set, initialization is complete. 

3. Otherwise, disable ASTs, remember previous state of AST enable, and retest the flag. 

4. If the flag is now set, initialization was performed by an AST that occurred between the first test 
and the AST disable; enable ASTs if remembered state of ASTs was enable. Initialization is now 
complete. 

5. Otherwise, perform the initialization. 

6. Set the flag. 

7. Enable ASTs if remembered state of ASTs was enable - initialization is complete. 


Note 

ASTs should only be enabled (Step 4 or Step 7) if they were enabled before Step 3. The 
$SETAST system service, used to disable ASTs, indicates whether ASTs were enabled 
when the procedure was called. 

For example, your procedure can use the VAX instructions INSQUE and REMQUE to maintain a set of 
queues whose headers are in static storage. However, to maintain a position-independent data 
region, the address in the queue header can be initialized only at run time. The STR$COPY proce¬ 
dures use these instructions to initialize dynamic string storage to a set of empty queues. Each 
allocation of dynamic string storage is performed by first trying to remove a preallocated block from the 
appropriate queue. 

The following BLISS fragment shows the code for opening a process permanent file on the first call. 
The code could be part of a GET routine. 


LOCAL 

RET_STATUS t ! RMS status 

FAB : $FAB_DECL, ! FAB 

RAB : $RAB_DECL5 ! RAB 


MAP 


GET _STRING : REF BLOCK C8 » BYTE] t ! 

PROMPT-STRING : REF BLOCK IB, BYTE] * ! 

GET_ISI : REF VECTOR Lit WORD * UNSIGNED] 5 
! static storage to remember ISI 


String d e s c. 
String d e s c♦ 
Place in 


(continued on next page) 
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f 


Enable a handler to return string signals as error 
codes to the caller* 

ENABLE 

LIB$SIG_TO_RET5 

IF (.GET-ISI C03 EQL 0) 

THEN 

First call# initialize FAB 
BEGIN 

$F AB_IN I T (FAB = FAB# FAC = GET# ! File access: GET 
FNA = .DEVICE-NAME# ! File name: DEO ICE-NAME 

FNS = ♦DEO ICE-NAME-LEN) 5 ! File name size 

Open D E 0 IC E-N A M E # remember RMS internal stream identifier 

RET_STATUS = $OPEN (FAB = FAB)5 ! Fab adr = FAB 

If the OPEN fails# return the RMS status code* 

IF ( NOT ♦ RET_ST ATUS) THEN RETURN ( *RET_STATUS ) 5 

$RAB_IN I T (FAB = FAB# RAB = RAB ) 5 

RET.STATUS = $CONNECT (RAB = RAB)5 ! Connect RAB to file 

If the CONNECT fails# return the RMS status code* 

IF ( NOT *RET_STATUS) THEN RETURN (♦RET_STATUS) 5 

GET-1SI C03 = ♦RAB [RAB$W_ISI35 ! Remember ISI 

END 

File already open# Just initialize RAB 
including ISI returned from first $ 0 P E N 

ELSE 

BEGIN 

$RAB_ I N I T (FAB = FAB# RAB = RAB ) 5 
RAB [RAB$H_ISI 3 = *GET_ISI [035 
END 5 

Continue setup and Set string 


Another example of performing first-time initialization transparent to the caller is to establish an exit 
handler to perform some cleanup operation once, when the image exits. Again, this is done by testing 
and then setting a first-time flag. If the flag is clear, the Declare Exit Handler system service 
($DCLEXH) is called to establish the exit handler. 

4.3.4 Adding a Dispatch Address to PSECT LIBSINITIALIZE 

To add a dispatch address to PSECT LIBSINITIALIZE, your module generates one or more longwords. 
Each longword contains the address of a procedure to be called by the system before the main 
program is called. Your module must declare these longwords to be part of the overlayed PSECT 
LIBSINITIALIZE. (Examples of this method are shown in Appendix B of the VAX-11 Run-Time Library 
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User's Guide.) A module in a shareable image cannot use this method because the PSECT contribu¬ 
tion would be to the shared image, not to the user program image. Furthermore, if a modular 
procedure adds a dispatch address to the PSECT LIB$INITIALIZE, there are restrictions on the type of 
condition handler it can establish. If it establishes a condition handler by calling LIB$INITIALIZE 
before a main program to alter how signaled errors are handled, the action of this handler may 
conflict with other condition handlers established by other procedures before the main program. 

4.4 Allocating Resources 

A resource is a part of the hardware or software system that can be allocated and deallocated. It is 
therefore either in use or free for use. For reliable operation, each instance of a resource must be 
allocated to only one owner at a time. All potential owners must agree beforehand on the technique 
for allocating each resource. 

There are process-wide resources and system-wide resources. System-wide resources, such as disk 
memory and physical memory, are allocated on behalf of a process by the operating system. Process¬ 
wide resources are allocated on behalf of a procedure activation executing within a single process. 

There are two methods of allocating process-wide resources: 

• A single software component is used by all procedures in the image to allocate (and/or deallocate) 
the resource. 

• A standard discipline is agreed on, so that many allocators can make nonconflicting allocations. 
For example, a single allocator is used when: 

• The linker allocates relocatable virtual addresses among the procedures that require resources in an 
image. 

• The $ASSIGN system service assigns an I/O channel number to each procedure in the process that 
needs a separate channel. 

• The library procedures LIB$GET_VM and FIB$FREE_VM allocate and deallocate virtual memory to 
requesting procedures in an image (see the VAX-11 Run-Time Library User's Guide for the process¬ 
wide resource allocating procedures provided by the system). 

The following examples illustrate the use of separate allocators for each procedure: 

• Each procedure allocates and deallocates its own stack storage using registers FP and SP to maintain 
discipline. 

• Each procedure allocates registers from the pool of process registers (R2 to R11) after saving the 
contents of these registers on the process stack using the entry mask mechanism. 

Table 4-1 shows process-wide resources. It also indicates the single software component that allo¬ 
cates the resource or the discipline used to prevent conflicts, for multiple allocators. 
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Table 4-1: Methods of Allocating Resources 


Resource 

Allocation Method 

RO, R1 

Not a shared resource. 

R2:R15 

Preserved using stack frame discipline (see Entry Point List). 

PSL 

Preserved using stack frame discipline. 

Virtual memory 

Allocated statically by linker. 


Allocated dynamically by either $EXPPRG or LIB$GET_VM. 


Deallocated dynamically only by LIB$FREE_VM. 

Static storage for non¬ 
resource-allocating procedures 

Procedure to push old contents onto a stack in heap storage 
and another to pop old contents back. 


Caller allocates storage. 

Process-wide identifiers for static 
storage 

Procedure to assign process-wide identifiers. 

Dynamic string memory 

Call LIB$, OTS$, or STR$ string procedures (see Chapter 2). 

VMS event flags 

Process local event flags 32-63 allocated by calling 
LIB$GET_EF. Process local event flags 1-23 and 32-63 can 
be reserved by calling LIB$RESERVE_EF. All can be freed by 
calling LIB$FREE_EF. 

BASIC/FORTRAN logical unit 
numbers (channel numbers) 

Process logical unit numbers 100-119 allocated by calling 
LIB$GET_LUN and freed by calling LIB$FREE_LUN. 

Condition codes (message IDs) 

Bits 27:16 contain the facility number. Bit 27 is 0 for those 
assigned by DIGITAL, and 1 for those assigned by customers. 

Each allocator must ensure uniqueness in bits 15:3. Also, the 
symbols for the completion status codes and signaled condi¬ 
tions are contained in a separate source file for each facility. 

Global Symbols 

DIGITAL—assigned symbols available to users contain a single 
"$". Within DIGITAL, a facility prefix identifies a person 
responsible for allocating unique symbols. Global symbols 
not available to users contain two dollar signs. User-defined 
symbols should contain an underscore (_) instead of a $ to 
avoid conflict with DIGITAL symbols. 


4.4.1 Using Storage with Resource-Allocating Procedures 

A resource-allocating procedure must use some static storage to keep track of allocated and deallo¬ 
cated resources. Therefore, all resource-allocating procedures should follow the special considera¬ 
tions needed by AST—reentrant procedures with static storage (see Chapter 6). 
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You cannot use BASIC and PASCAL to write modular resource-allocating procedures because: 

• BASIC does not use static storage in a module. 

• PASCAL uses static storage at the module level, but the module-level declarations must match those 
in the main program. 


4.4.2 Allocating Identification Numbers 

The following MACRO procedure LIB_GET_INUM allocates identifying numbers that can be used to 
identify a resource: 


TAB : 

♦ WORD 

0 

5 Bitmap 

for f 1 a 3 s 


♦ENTRY 

L I B_GET_INUM, % M< > 




FFC 

#10, TAB , R0 

5 Find fi 

rst free id* no* 


BEQ 

20$ 

5 Branch 

if none free 


BBSS 

R0 , TAB, 10$ 

5 Ind i cat 

e id* no* in us e 

10$: 

MOVL 

R0, @4<AP) 

5 Return 

id* no* f o u n d 


MOVL 

RET 

#1 , R0 

5 I n d i c a t 

e success 

20$: 

CLRL 

@4(AP) 

5 Retur n 

0 


CLRL 

R0 

5 I n d i c a t 

e failure 


RET 
♦ END 

To make this procedure AST-reentrant, move the label 10$ from the MOVL instruction to the FFC 
instruction. (See Section 6.3.2.) 

The equivalent FORTRAN module contains procedures to allocate and deallocate identifying 
numbers: 


FUNCTION LIB_GET_INUM (INUM) 


INTEGER*^ INUM, 

INUM_TABLE( 

: ioo) 


LIB_GET_INUM = 

1 


! Assume success 

DO 10 1=1,100 




IF(INUM_TABLE 

(I) ♦EQ♦ 0) 

THEN 


INUM_T ABLE 

( I ) = 1 


! F1 a S unit as in 

INUM = 1-1 




RETURN 



! Return id* n o♦ 

END I F 




CONTINUE 




LIB_GET_INUM = 

0 


! Indicate failure 


RETURN 


C Deallocate identifying number 

ENTRY LIB_FREE_INUM 

IF ( INUM_TABLE( INUM+1 ) ♦ EQ ♦ 1 THEN 

INUM_TABLE(INUM+1 ) = 0 ! FI 

LIB_FREE_INUM = 1 ! In 

ELSE IF 

LIB_FREE_INUM = 0 ! In 

END I F 
RETURN 
END 


a S unit as free 
dicate success 

dicate already free 
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LIB_GET_INUM can be called from a FORTRAN program as follows: 


IF ♦NOT* (LIB_GET_INUM(I)) THEN GO TO error 
♦ ♦ ♦ = I 


4.5 Passing Strings as Parameters 

This section describes how a procedure can accept and return string parameters. 

Calling programs pass string parameters by descriptor. The calling program must either allocate the 
space identified by the string's address or pass to the modular procedure the address of a descriptor 
that another calling program has passed to it. 

The descriptor contains a descriptor class code. The called procedure reads the class code to deter¬ 
mine how to read and write the input and output strings. 

The VAX-11 Run-Time Library follows conventions that define the relationship between the string 
descriptor classes and the semantics of string parameters. Your procedure should also follow these 
string-handling conventions to ensure that your procedure interacts correctly with components of 
VAX/VMS. These conventions are described in the VAX-11 Run-Time Library User's Guide, 
Chapter 4. 

4.5.1 Accepting Input String Parameters 

Your procedure should read the class code field of the descriptor passed to it, to determine how the 
input string is to be read. For each descriptor, Table 4-2 indicates which field the procedure reads to 
determine the length and address of the string's contents. 

Table 4-2: How Modular Procedures Read Strings 


Class 

Length 

Address of First Byte of Data 

Z 

DSC$W_LENGTH 

DSC$A_POINTER 

s 

DSC$W_LENGTH 

DSC$A_POINTER 

D 

DSC$W_LENGTH 

DSC$A_POINTER 

A 

DSC$I_ARSIZE 

DSC$A_ POINTER 

SD 

DSC$W_LENGTH 

DSC$A_POINTER 

NCA 

DSC$I_ARSIZE 

DSC$A_POINTER 

VS 

Word at DSC$A_POINTER 
(CURLEN field) 

Value of DSC$A_POINTER + 2 
(Byte after CURLEN field) 


4.5.2 Returning Output String Parameters 

A called procedure can return three types of strings, depending on the conventions used to determine 
the current length and maximum length of the string. These conventions are called semantics. This 
section describes the semantics of returning fixed-length, varying-length, or dynamic strings as output 
parameters or as a function value. 
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The calling procedure can pass a string whose class (DSC$K_CLASS) is any of the following: 

• Z - unspecified 

• S - static string 

• D — dynamic string 
•A - array 

• SD - scaled decimal 

• NCA - noncontiguous array 
•VS - varying string 

Your procedure should return strings of class S, Z, NCA, SD, and A using fixed-length semantics. 
Special restrictions apply to classes NCA, SD, and A. The semantics for writing output strings depend 
on the descriptor class of the input string. Table 4-3 summarizes this relationship. 


Table 4-3: Semantics and Descriptor Classes — Writing 


Class 

Description 

Restrictions 

Writing 

Semantics 

Z 

Unspecified 

Treated as class S 

Fixed string 

s 

Scalar, string 

None 

Fixed string 

D 

Dynamic string 

String length < 64K bytes 
(DSC$W_LENGTH < 64K) 

Dynamic string 

A 

Array 

Array is one-dimensional 
(DSC$B_DIMCT = 1) 

String length < 64K bytes 

(DSC$I_ARSIZE < 64K) 

Data type is unsigned byte or unspecified 
(DSC$B_DTYPE = BU, Z) 

Length of array elements is one byte 
(DSC$W_LENGTH = 1) 

Fixed string 

SD 

Decimal scalar 

DSC$B_DIGITS and DSC$B_SCALE are ignored 

Fixed string 

NCA 

Noncontiguous 

array 

Array is one-dimensional 
(DSC$B_DIMCT = 1) 

String length < 64K bytes 

(DSC$I_ARSIZE < 64K) 

Data type is unsigned byte or unspecified 
(DSC$B_DTYPE = BU, Z) 

Array is contiguous 

(DSC$I_SI = DSC$W_LENGTH) 

Length of array elements is one byte 
(DSC$W_LENGTH = 1) 

Fixed string 

VS 

Varying string 

Current length is less than maximum length of string 
(CURLEN < = DSC$W_MAXSTRLEN) 

Varying string 
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The semantics for returning a fixed-length string are: 


• The called procedure does not modify the string descriptor passed by the calling program. 

• The called procedure writes the string starting at the address specified in the descriptor 
(DSC$A_POINTER). The called procedure determines the length of the string as described in Table 
4-2. If the actual string length indicated in the descriptor is not the correct size, the called proce¬ 
dure fills the string with trailing ASCII spaces or truncates it on the right. 

• If truncation occurs, the called procedure can return either: (1) the success condition value 
LIB$_STRTRU, (2) the warning condition value STR$_TRU, or (3) an error condition value as a 
completion status in RO depending upon the application. 


The semantics for returning a varying-length string are the same as for fixed-length strings, except that 
no space padding takes place and the CURLEN field of the descriptor is updated to reflect the current 
length of the string. The value of CURLEN cannot exceed the value of MAXSTRLEN. 

The semantics for returning a dynamic string are: 

• The called procedure can modify the string descriptor passed by the calling program only if the 
descriptor class code is dynamic (DSC$K_CLASS_D). 

• The called procedure must use the string resource allocation and deallocation procedures or the 
string copying procedures to modify the string descriptor passed by the calling program. 

• Using the dynamic descriptor passed by the calling program, the called procedure can use either of 
these methods: 

— Create the entire string to be returned and pass it to STR$COPY_DX or STR$COPY_R. The 
string is copied using the dynamic descriptor as the destination. 

- Allocate the total amount of string space needed (by calling STR$GET1_DX using the descriptor 
passed by the calling program) and fill the dynamically allocated area piece-by-piece using the 
modified contents of the descriptor. 

• If the resource-allocating string procedure exhausts the virtual memory for your process, your 
procedure should also indicate the error to the calling program by either: (1) returning the error 
condition value in RO (LIB$ convention) or (2) signaling the error condition (STR$ convention). 

• The called procedure cannot make a copy of the dynamic string descriptor since its contents can 
change whenever the string is written. Therefore, each dynamic string must have one and only one 
dynamic string descriptor pointing to it. However, the descriptor can be copied to a local fixed- 
length string descriptor. 

Table 4—4 shows the action your procedure takes for all combinations of interface specification and 
descriptor class passed by the calling program: 
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Table 4-4: Procedure's Action for Strings Passed by Calling Program 


String Passed 
by Calling 
Program 

Interface Specification for Output String 

Fixed-length 

sematics 

(-.wt.ds) 

(ignore DSC$K_CLASS) 

Semantics specified 
by calling program 
(-.wt.dx) 

(observed DSC$K_CLASS) 

Fixed-length 
(DSC$K_CLASS = 0,1) 

Space fill or 
truncate using 
DSC$W_LENGTH and 
DSC$A_POINTER 

Space fill or 
truncate using 
DSC$W_LENGTH and 
DSC$A_POINTER 

Dynamic 

(DSC$K_CLASS = 2) 

Not permitted 

Use library dynamic 
string procedures 

Varying-length 
(DSC$K_CLASS =11) 

Not permitted 

Update CURLEN and 
truncate using CURLEN 
and DSC$A_POINTER-F2 

Array 

(DSC$K_CLASS = 4) 

Not permitted 

Space fill or 
truncate using 

DSC$I_ARSIZE and 

DSC$A_POINTER 

Noncontiguous 
(DSC$K_CLASS = 10) 

Not permitted 

Space fill or 
truncate using 

DSC$I_ARSIZE and 

DSC$A_POINTER 

Scaled decimal 
(DSC$K_CLASS = 9) 

Not permitted 

Space fill or 
truncate using 
DSC$W_LENGTH and 
DSC$A_POINTER; 
scale factor ignored 


4.5.3 Passing String Parameters to Other Procedures 

The following restrictions apply to string parameters passed from the calling program to your proce¬ 
dure, and then from your procedure to another procedure: 

• If you have specified that your procedure (and any it calls) only accesses the string as an input 
parameter, your procedure can pass the address of either (1) the original descriptor (preferred) or 
(2) a copy of the descriptor. 

• If the parameter being passed is a dynamic string (DSC$K_CLASS_D), and if you have specified 
that your procedure (and any it calls) accesses the parameter as an output parameter using fixed- 
length semantics (wt.ds), your procedure can pass the address of one of the following: 

— The original descriptor (to any procedure accessing it) 

- A copy of the descriptor in which the class code field has been forced to fixed-length 
(DSC$K_CLASS_S = 1) to any procedure accessing it as output using the semantics specified 
by the calling program (wt.dx). 
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• If you have specified that your procedure (or any it calls) accesses the parameter as an output 
parameter using the semantics specified by the calling program, your procedure must pass the 
address of the original descriptor: a dynamic string must have one and only one descriptor pointing 
to it. 

• If you do not know the semantics used by a procedure that your procedure calls, you should 
assume the most general case and pass the address of the original descriptor, not a copy of the 
descriptor. 

4.6 Using VAX/VMS System Services 

Not all VAX/VMS system services are modular, according to the definitions in this manual. Proce¬ 
dures that call nonmodular system services are nonmodular themselves. If your procedure uses a 

nonmodular system service, you should list the system service in the SIDE EFFECTS section of the 

procedure description. 

This section consists of a table listing VAX/VMS system services by categories. In each table: 

• The first column lists the system service. 

• The second column describes the function of the system service. 

• The third column tells whether the system service is modular or not. 

• The fourth column refers to the list of notes at the end of the table. 

Table 4-5: VAX/VMS System Services and Modularity 
System 


Service 

Function 

Modular? 

See Note: 

Event Flag Services 

$ASCEFC 

Associate Common Event Flag Cluster 

no 

16 

$DACEFC 

Disassociate Common Event Flag Cluster 

no 

16 

$DLCEFC 

Delete Common Event Flag Cluster 

no 

16 

$SETEF 

Set Event Flag 

yes 

1 

$CLREF 

Clear Event Flag 

yes 

1 

$READEF 

Read Flag 

yes 


SWAITFR 

Wait For Single Event Flag 

yes 

1 

$WFLOR 

Wait For Logical OR of Event Flag 

yes 

1 

$WFLAND Wait For Logical AND of Event Flag 

Asynchronous System Trap (AST) Services 

yes 

1 

SSETAST 

Set AST Enable 

yes 

15 

$DCLAST 

Declare AST 

yes 


$SETPRA 

Set Power Recovery AST 

yes 


$CLRAST 

Clear AST Enable 

no 

2,5 


(continued on next page) 
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Table 4-5: VAX/VMS System Services and Modularity (Cont.) 


System 


Service 

Function 

Modular? 

See Note: 

Logical Name System Services — See Note 19. 



$CRELOG 

Create Logical Name 

no 

2,13 

$DELLOG 

Delete Logical Name 

no 

3,13 

$TRNLOG 

Translate Logical Name 

yes 


I/O System Services 



$ASSIGN 

Assign 1 /O Channel 

yes 


$DASSGN 

Deassign I/O Channel 

yes 

3 

$QIO 

Queue I/O Request 

yes 

1 

$QIOW 

Queue I/O Request and Wait For Event Flag 

yes 

1 

$INPUT 

Queue Input Request and Wait For Event Flag 

yes 

1 

$OUTPUT 

Queue Output Request and Wait For Event Flag 

yes 

1 

$ALLOC 

Allocate Device 

yes 


$DALLOC 

Deallocate Device 

yes 

1 

$GETCHN 

Get I/O Channel Interface 

yes 


SGETDEV 

Get I/O Device Information 

yes 


SGETCHN 

Get I/O Channel Information 

yes 


$CANCEL 

Cancel I/O on Channel 

no 

3 

SCREMBX 

Create Mailbox and Assign Channel 

no 

2,13 

$DELMBX 

Delete Mailbox 

yes 

3 

$BRDCST 

Send Message to All Terminals 

no 


$SNDACC 

Send Message to Accounting Manager 

yes 


$SNDSMB 

Send Message to Symbiont Manager 

yes 


$SNDERR 

Send Message to Error Logger 

yes 


$SNDOPR 

Send Message to Operator 

yes 



Process Control Services — See Note 20. 


$CREPRC 

Create Process 

yes 

4 

$DELPRC 

Delete Process 

yes 

3,4 

$SUSPND 

Suspend Process 

yes 

3,4 

$RESUME 

Resume Process 

yes 

3,4 

$HIBER 

Hibernate 

yes 


$WAKE 

Wakeup 

yes 

3 

$SCHDWK 

Schedule Wakeup 

yes 

3,4 

$CANWAK 

Cancel Wakeup 

yes 

3,4 


(continued on next page) 
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Table 4-5: VAX/VMS System Services and Modularity (Cont.) 


System 

Service Function Modular? See Note: 


Process Control Services (Cont.) —See Note 20. 


$EXIT 

Exit 

no 

5 

$FORCEX 

Force Exit 

yes 

3 

$DCLEXH 

Declare Exit Handler 

yes 


SCANEXH 

Cancel Exit Handler 

yes 


$SETPRN 

Set Process Name 

no 

3,4 

$SETPRI 

Set Priority 

yes 

3 

$SETRWM 

Set Resource Wait Mode 

no 

2 

$GET)PI 

Get Job/Process Information 

yes 

4 

SSETPRV 

Set Privileges 

yes 

3 

Timer and Time Conversion System Services 



SGETTIM 

Get Time 

yes 


$NUMTIM 

Convert Binary Time to Numeric Time 

yes 


$ASCTIM 

Convert Binary Time to ASCII String 

yes 


$BINTIM 

Convert ASCII String to Binary Time 

yes 


$SETIMR 

Set Timer 

yes 

1 

SCANTIM 

Cancel Timer Request 

yes 

1 

$SETIME 

Set System Time 

no 

2 

Condition Handling System Services 



$SETEXV 

Set Exception Vector 

no 

2 

SSETSFM 

Set System Service Failure Exception Mode 

no 

2 

SUNWIND 

Unwind Stack 

yes 


$DCLCMH 

Declare Change Mode or Compatibility Mode Handler 

no 

8 

Memory Management System Services 



SEXPREG 

Expand Program/Control Region 

yes 

11 

$CNTREG 

Contract Program/Control Region 

no 

6 

$CRETVA 

Create Virtual Address Space 

yes 

17 

$DELTVA 

Delete Virtual Address Space 

yes 

17 

$CRMPSC 

Create and Map Global Section 

yes 

7,18 

$UPDSEC 

Update Global Section File on Disk 

no 

7 

$MGBLSC 

Map Global Section 

yes 

7,18 

$DGBLSC 

Delete Global Section 

yes 

3 

$LKWSET 

Lock Pages in Working Set 

no 

5 

$ULWSET 

Unlock Pages from Working Set 

no 

5 


(continued on next page) 
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Table 4-5: VAX/VMS System Services and Modularity (Cont.) 


System 

Service Function Modular? 


Memory Management System Services (Cont.) 


$PURGWS Purge Working Set 

$LCKPAG Lock Page in Memory 

$ULKPAG Unlock Page from Memory 

$ADJWSL Adjust Working Set Limit 

$SETPRT Set Protection on Pages 

$SETSWM Set Process Swap Mode 

Change Mode System Services 
$CMEXEC Change Mode to Executive Mode 

$CMKRNL Change Mode to Kernel Mode 

$ADJSTK Adjust Outer Mode Stack Pointer 


Error Messages — See Note 21. 

$GETMSG Get Message 

$PUTMSG Put Message 

Formatted ASCII Output 

$FAO Formatted ASCII Output 

$FAOL Formatted ASCII Output with List Parameter 

RMS System Services —See Note 22. 


$CLOSE 

$CONNECT 

$CREATE 

$DELETE 

$DISCONNECT 

$DISPLAY 

$ERASE 

$EXTEND 

$FIND 

$FLUSH 

$FREE 

$GET 

$NXTVOL 

$OPEN 

$PUT 


CLOSE file 

CONNECT I/O stream 
CREATE file 
DELETE record 
DISCONNECT I/O stream 
DISPLAY information 
ERASE file 
EXTEND file 
FIND record 

Write out all modified I/O buffers 
Unlock all previously locked records 
GET record 

Magnetic tape processing continues to next volume 
Open File 

Write a new record to a file 


yes 

no 

no 

no 

yes 

no 

no 

no 

no 


yes 

yes 

yes 

yes 

yes 

yes 

yes 

yes 

yes 

yes 

yes 

yes 

yes 

yes 

yes 

yes 

yes 

yes 

yes 


See Note: 


8 

8 

8 

17 

5 

8 

8 

8 


10,12 


3 

9 

3 

3 

3 


3 

3 

14 

9 

14 


(continued on next page) 
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Table 4-5: VAX /VMS System Services and Modularity (Cont.) 


System 


Service 

Function 

Modular? 

See Note: 

RMS System Services (Cont.) —See Note 22. 



$READ 

Retrieve a specified number of bytes from a file 

yes 


$RELEASE 

Unlock a record pointed to by RFA field 

yes 

3 

$REWIND 

Position first record of a file 

yes 


$SPACE 

Space forward or backward in a file 

yes 


$TRUNCATE 

Truncate a sequential file 

yes 


$UPDATE 

Update an Existing Record 

yes 


$WAIT 

Determine completion of asynchronous operation 

yes 

3 

$WRITE 

Write specified number of bytes to a file 

yes 



Notes to Table 4—5 

1. This service has a process-wide resource (event flag) as an input parameter. To ensure that 
you have allocated a unique process local event flag, you must use the library procedures 
LIB$GET_EF and LIB$FREE_EF. 

2. This service changes the default storage type that modular procedures expect to process¬ 
wide static storage. Thus, use by more than one procedure could cause a conflict. Further 
problems result if an AST interrupt occurs while static storage is in a nondefault state. 

3. A module can only deallocate or operate upon items (for example, processes, memory, 
devices, global sections) that are known to have been allocated by it. 

4. No process name can be specified, since there would have to be a group-wide allocator to 
allocate a unique process name within the group. 

5. This service could adversely affect the execution of other modular or reentrant procedures in 
the process. 

6. You cannot use $CNTREG to contract the program or control region, because a procedure 
cannot rely on a particular value of an implicit input. Some other procedure might have 
expanded the region after you had expanded it. 

7. These services need a system-wide, group-wide, or process-wide allocation procedure or 
discipline. 

8. These services could adversely affect the execution of user-written procedures that are not 
modular reentrant because they are also using these system services. 

9. File names must be passed as explicit arguments or derived from explicit arguments passed 
to a modular procedure from a nonmodular procedure or from a user via SYS$INPUT. 

10. Use LIB$SIGNAL instead. This lets the caller write application-specific error messages. 

11. If LIB$FREE_VM deallocates space in the program region, LIB$GET_VM must be called to 
reuse the deallocated space. (See the VAX—7 7 Run-Time Library Reference Manual.) 
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12. Modular procedures should provide an optional action routine parameter so that the calling 
program can control human-readable output. 

13. This service needs a logical name allocation procedure. 

14. To ensure that the procedure is AST-reentrant when using $GET and $PUT, check for record 
stream active error (RMS$_RSA). If the error is encountered, call $WAIT and try again. (See 
Section 6.4.) 

15. To use $SETAST in a modular procedure, you must save the old setting and restore it before 
returning to the calling program. You must also establish a condition handler to restore the 
setting in case of a stack unwind. 

16. For modularity, this service requires a resource-allocating procedure to allocate event flag 
cluster numbers 2 and 3. The VAX-11 Run-Time Library does not provide such a procedure. 

17. This service applies only to pages that were statically or dynamically allocated to your 
procedure. 

18. $CRMPSC and SMGBLSC apply only with the SEC$M_EXPREG flag that creates or maps a 
global section into the first available space set. 

19. VMS stores logical names in process-wide storage. Therefore, they cause the same modu¬ 
larity problems as other static storage. 

20. When using the process control services, you must specify the process name parameter as 
zero; otherwise, a resource allocation procedure is needed to assign different values. 

21. The error message identification (32—bit condition code) has an allocation discipline in 
which bits 26:16 are assigned by DIGITAL as facility codes. For each facility, the unique¬ 
ness of bits 15:3 is guaranteed. However, for correct modularity, all modular procedures 
must use LIB$SIGNAL (or LIB$STOP) error handling rather than outputting an error message 
themselves. Only the Catch-all Handler can use the following system services. 

22. The file name is passed as an explicit parameter or is derived from an explicit parameter 
passed to a modular procedure from a nonmodular procedure or from a user. Otherwise, the 
file name can conflict with one that already exists. Do not use the RMS optional success and 
error action routines; they depend on AST interrupts being enabled even for synchronous 
I/O. This dependency is not appropriate for modular procedures. 

In principle, a modular procedure could: (1) save and enable ASTs using $SETAST (see note 
15), (2) do synchronous RMS I/O with action routines, and (3) restore the AST enables. 
However, the extra overhead would probably not be worth the trouble. 

4.7 Invoking Optional User Action Routines 

An optional user action routine is a useful way to let the calling program gain control at a critical 
point in your procedure's algorithm. 

A user action routine must be passed as a parameter to the called procedure. There are two VAX—11 
data types used to represent a procedure to be passed as a parameter. The first, and simplest, is used 
by FORTRAN and is expected by the Run-Time Library, RMS, and VMS System Services. It is called 
Entry Mask (ZEM). The second is used by PASCAL and other languages where a particular procedure 
activation must be specified. The procedure might do up-level addressing of a variable defined in a 
syntactically outer block and hence, allocated in another frame. It is called Bound Procedure Value 
(BPV). 
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For ZEM passed by reference, the argument list entry contains the address of the procedure entry 
mask to be called. For BPV passed by reference, the argument list entry contains the address of two 
longwords. The first longword contains the address of the procedure and the second contains the 
environment pointer to be loaded into R1 before the procedure is called. The VAX-11 Procedure 
Calling Standard explicitly permits a BPV data type to be passed by immediate value, in which case 
the second longword is omitted entirely, and the first longword (address of entry mask) is placed in 
the argument list entry making it identical to ZEM passed by reference. 

To provide a user-action routine interface for your procedure, you must first decide whether to use 
the ZEM or BPV data type. Since higher-level languages that support BPV by default, must provide the 
language extension to force immediate value, ZEM is more language-independent. However, ZEM is 
more awkward for calling programs written in languages like PASCAL. 

To make it easy for the calling program to pass information to its action routine your procedure 
should supply an optional user-arg parameter that the calling program can pass to its action routine. 
Your procedure merely copies the argument list entry of the user-arg, if present, to the argument list it 
passes to the action routine. This achieves the same effect as up-level addressing. 

Often it is convenient to specify a default action if the optional action routine is not supplied by the 
calling program. 

To provide a user action routine, your procedure should have the following calling sequence: 

CALL myproc (...[,action-routine.fzemlc.r[,user-arg.xy.z]]) 
or 

CALL myproc (...[,action-routine.fbpvlc.r[,user-arg.xy.z]]) 

The user action routine has the calling sequence: 
status.wlc.v = action-routine (...[,user-arg.xy.z]) 

where your procedure copies the 32-bit argument list entry passed by the calling program to the 
argument list provided to the action routine. Thus, the calling program and its action routine can 
communicate using any data type, access type, passing mechanism, or parameter form. 

The following code fragment shows how to test for the presence of an optional user action routine 
and pass it a line of text and the optional user argument. If no user action routine is supplied, 
LIB$PUT_OUTPUT is called as the default action routine. 

♦♦4=4 i Formal 1 - ♦♦♦ 

ACTION-ROUTINE = 8 5 Formal 2 - action routine 

USER_ARG = 12 5 Formal 3 - user a r S 

♦ENTRY MYPROC "M< ♦♦♦ > 


M 0 0 A Q ♦ ♦ ♦ * R 0 5 R 0 = a d r♦ of string d e s c r♦ for line 

CM PB (AP) » *<ACTI0N_R0UTINE>4* 

5 Test n o♦ of caller parameters 


BLSSU 

30$ 

5 Branch if no action 

routine specified 

TSTL 

ACTION 

-ROUTINE(AP ) 


Test for ( 

> action 

routine a dr♦ 


BEOU 

30$ 

5 Branch if no action 

5 (LIB $ convention) 

routine specified 

CM PB 

(AP) » 

**< USER_ARG >4* 



(continued on next page) 
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; Test no* of caller parameters 

BLSSU 20$ 5 Branch if no optional user-ar* par* 

5 + 

5 Call user action routine (ZEM) with optional user-ar* parameter 
5 - 

PUSHL USER_ARG(AP) 5 2nd par = user-arS list entry 

PUSHL RO ? 1st par = adr* of string descr* 

CALLS #2> @ACTION_ROUTINE(AP) 

? Call user action routine 

B R B 4 0 $ ! Join common code 

5 + 

5 Call user action routine (ZEM) without optional use r- a r S parameter 

5 - 

20$: PUSHL RO 5 1st par = adr* of strinS descr* 

CALLS #1, @ACTIOIM_ROUTINE(AP) 

5 Call user action routine 
BRB 40$ 

5 + 

5 Call LIB$PUT_OUTPUT - caller did not supply user action routine* 

5 - 

30$: PUSHL RO 5 1st par = adr* of string descr* 

CALLS #1 > LIB$PUT_OUTPUT 

5 Output line to SYS$OUTPUT 

40$: BLBC R0 *♦ ♦ ♦ ? Test for error status 

To call a BPV user action routine replace the two CALLS instructions with the following 

MOOQ/r. @ACTION-ROUTINE(AP) 5 RO = address of procedure > 

5 R1 = environme n t v a 1 u e 

CALLS # n t (R 0) 5 Call user supplied action routine 

where n is 2 and 1, respectively. 
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Chapter 5 

Signaling and Condition Handling by Modular 
Procedures 


A modular procedure should not print error or informational messages, either directly on an output 
device or by calling the $PUTMSG system service. 

Instead, a modular procedure uses either of these techniques: 

• It returns a condition value as a function value (preferred). (See Section 5.2.) 

• It signals a condition value by calling LIB$SIGNAL or LIB$STOP when a failure occurs. The 
absence of a signal indicates success. (See Section 5.3 of this manual and Chapter 6 of the VAX—7 7 
Run-Time Library User's Guide.) 

Otherwise, the calling program cannot override the actions taken by your procedure, to alter the error 
message or change the flow of control. For example, your procedure may generate an error message 
intended for a systems programmer (such as "MRS, maximum record size invalid"). If the calling 
program is being run by a nonprogramming clerk, however, you might wish to change the message to 
a more useful form (such as "Please start over"). The techniques described here allow you to do this. 

5.1 Returning a Condition Value as a Function Value 

A condition value is a 32-bit quantity. Success or failure is indicated in bit 0 as a one or zero. Besides 
indicating success or failure of your program, the condition value can provide this information: 

• Severity of the failure 

• Error identification 

• Associated message text 

• Facility detecting the error 

• Control of error message printing 
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The format of the condition value is: 


31 28 27 


3 2 


cntrl 


condition identification 


severity 


i, 


27 26 25 


facility number 


message number 


where: 

condition identification (STS$V_COND_ID) 

Identifies the condition uniquely on a system-wide basis. 

facility number (STS$V_FAC_NO) 

Identifies the software component generating the condition value. Bit 27 is set for customer 
facilities and clear for DIGITAL facilities. 


message number (STS$V_MSG_NO) 

A status identification, that is, a description of the hardware exception that occurred or of a 
software-defined value. Message numbers with bit 15 set are specific to a single facility. Message 
numbers with bit 15 clear are system-wide and hence reserved to DIGITAL. 


severity (STS$V_SEVERITY) 

Indicates the severity code: bit 0 is set for success (logical true) and is clear for failure (logical 
false); bits 1 and 2 distinguish degrees of success or failure. Taken together the bits 0 through 2 
define the severity of the error as follows: 


STS$K_WARNING 

STS$K_SUCCESS 

STS$K_ERROR 

STS$K_INFO 

STS$K_SEVERE 


0 = warning 

1 = success 

2 = error 

3 = information 

4 = severe-error 


cntrl 

Four control bits. Bit 28 is set to stop the $EXIT system service from printing the message associ¬ 
ated with the condition value. It should be set in the condition value returned by a procedure as a 
function value if the procedure has also signaled the condition. Bits 29 thru 31 must be zero; they 
are reserved for DIGITAL. 


A list of facility numbers and codes is found in Appendix B of this manual. To distinguish your 
condition values from those used by DIGITAL, you should set bits 15 (STS$V_FAC_SP) and 27 
(STS$V_CUST_DEF) to one. 
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When your procedure returns a condition value as a function value to the calling program, you gain 
several advantages: 

• All execution paths are confined to syntactic blocks that have a single entry and a single exit point 
from the calling program's viewpoint. 

• Error contingencies are considered when the calling program is written, thereby increasing program 
reliability. 

• The action of the calling program is clearly indicated when errors occur. 

If your procedure is called as a main program, the condition value will be returned to the command 
language interpreter. 

5.1.1 Returning and Checking an Error Status 

The following examples illustrate how to check the condition value for success or failure. This is the 
simplest way to return and test the condition value. The method involves these steps: 

• Declare your procedure as a function that returns an integer. 

• Insert an IF statement to test for successful completion. 

• If the procedure completed successfully, set the function value equal to one. 

• Otherwise, set the function value equal to zero. 

• The calling program then tests the function value; one indicates success, zero indicates failure. This 
technique works whether your procedure returns a simple error code or a symbolic condition 
value, since the low bit of the condition value is used to indicate success or failure. 

Often, it is more useful to test the condition value for specific errors. This technique is described in 
Section 5.1.3. 

• MACRO 

The called procedure returns success or failure as a function value: 

♦ ENTRY PROC * M< ♦ ♦ ♦ > 


Success return 

M 0 V L * 1 t R 0 ! RO = 1 - success 

RET 

Failure return 

C L R L R 0 ! RO = 0 - failure 

RET 


The calling program tests the function value with a Branch On Low Bit Clear instruction. 
♦EXTRN PROC 

CALLG ARGLST t PROC i call procedure 

B L B C R0 t 10$ ? branch on error 
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• BLISS 


The called procedure: 

GLOBAL ROUTINE PROC (X»Y>Z) = 

BEGIN 


♦ 

IF ♦♦♦ THEN RETURN 1 ELSE RETURN 0 
END 


The calling program: 


EXTERNAL ROUTINE PROC5 
IF PROC (A,B,C) 

THEN 

success 

ELSE 

failure ? 


• BASIC 

The called procedure: 


100 FUNCTION INTEGER PROC(X*Y»Z) 


♦ 

200 IF (♦♦♦) THEN 
PROC = 17. 

ELSE 

PROC = 07. 
300 FUNCTIONEND 


The calling program: 

100 EXTERNAL INTEGER FUNCTION PROC 
200 IF (PROC (A > B > C) and 17.) THEN 
success 

ELSE 

failure 


• FORTRAN 

The called procedure: 


FUNCTION PROC (X»Y»Z) 
INTEGER4 PROC 


♦ 

IF (♦♦♦) THEN 
PROC = 1 

ELSE 

PROC = 0 
END I F 
RETURN 
END 
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The calling program: 

EXTERNAL PRDC 
INTEGER4 PROC 


♦ 

IF (PROC ( A »B »C ) ) THEN 
success 

ELBE 

failure 
END I F 


• PASCAL 

The called procedure: 

FUNCTION PROC < X 5 . * . » Y: ♦ ♦ ♦ * Z: ♦ ♦ ♦ ) sINTEGER 5 


IF (♦♦*) THEN 
PROC = 1 

ELSE 

PROC = 0 

END ; 

The calling program: 

PROCEDURE PROC (Ms*..# N:••* * 0:♦♦♦):INTEGER5EXTERN? 

IF ODD PROC (A# B* C) THEN success? 

5.1.2 Defining Condition Value Symbols 

To make condition value symbols available to calling programs in a convenient manner, you should 
assign a unique global symbol to each distinct error your procedure detects. The global symbols 
should have the form: 

fac$_error-name (DIGITAL-supplied) 
fac_error-name (User-supplied) 

You can also define success condition values in order to indicate various forms of success. For 
example, the system service $SETEF (Set Event Flag) can return to different success status values, 
SS$_WASCLR or SS$_WASSET, to indicate whether the event flag was previously clear or set. 

If you place your procedures in a user-created library, you can include the global symbol definitions 
there as well so they are available to any module making an external declaration. 

To uniquely define condition value symbols so neither the name nor the value can duplicate those 
defined by another user or by DIGITAL, you must: 

1. Choose an existing facility name or create one. If you create one, you must register it with 
someone at your installation responsible for the uniqueness of such symbols. This person will 
assign a unique 12-bit number to be used in the STS$V_FAC_NO field. Bit 27 must be set for 
non—DIGITAL facilities. 

2. Place all symbol definitions for a given facility in a single source file. 
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3. Define values for each symbol such that each value is unique in bits 14 through 3. 

4. Make sure that bits 27 and 15 are set to prevent conflict with DIGITAL-supplied software. 

5. Set bits 27 through 16 to the correct facility number. 


For example, assume that you wish to define the following set of global condition value symbols: 

LIB_NOSUCHFILE - no such file 

LIB_NOSUCHDEV - no such device 

LIB_NOSUCHDIR — no such directory 

The following examples illustrate the steps involved. 

• MACRO 

Assume the LIB facility has facility number 24, which is placed in a field ending at bit 16. Bits 27 
and 15 are set to one. The severity is set to SEVERE (bits 0 through 2 = 4). 


ine facility 
ty = SEVERE 


• BLISS 


GLOBAL LITERAL 

LIB_FAC = 24 A 1G + 1 A 27 + 1*1 

SEVERE = 4 

LIB_NOSUCHFILE = LIB__FAC + SEVERE + 1*3# 

LIB_NOSUCHDEV = LIB__FAC + SEVERE + 2”3> 

LIB_NOSUCHDIR = LIB„FAC + SEVERE + 3 A 35 


LIB_FAC = <24016 > 

SEVERE = 4 

LIB_NOSUCHFILE == 

LIB_NOSUCHDEV == 

LIB_NOSUCHDIR == 


+ <1@27 > + <1@15 > 5 Def 

5 S e u e r i 

L I B — FAC + SEVERE + 103 

LIB_FAC + SEVERE + 203 

LIB_FAC + SEVERE + 303 


• BASIC, FORTRAN, PASCAL 

Global symbols can be defined in MACRO for use by a BASIC, FORTRAN, or PASCAL program or 
procedure. 


5.1.3 Using Global Condition Values in a Calling Program 

A calling program can identify a condition value and take action for each specific value returned. 
When identifying a condition value, the calling program should ignore bits 31 through 28 and bits 2 
through 0 since they are supplemental to the identification of the error. In some cases, the condition 
value may have been signaled before being returned as a function value. Therefore, these bits may 
differ from the values defined symbolically. If the facility-specific bit (bit 15) is 0, then the facility 
number field (bits 27 through 16) should also be ignored. 

The library procedure LIB$MATCH_COND uses this algorithm for matching condition values. This 
procedure is described in the VAX—7 7 Run-Time Library Reference Manual. 
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The format for LIB$MATCH_COND is: 


index = LIB$MATCH_COND (condition-value, cond-value-i ...) 


condition-value 

Address of longword containing the condition value to be matched, 
cond-value-i 

Address of longword containing the condition value to be compared with condition-value. 
index 

If no match is found, index is zero. If a match is found between condition-value and parameter 
number /, index equals / - 1. That is, if condition-value matches the first parameter following itself 
in the parameter list (parameter number two), index equals 1. 

The following sections show examples that use the condition values previously defined in a program 
(see the previous section) to branch to different instructions on each different condition value. Exam¬ 
ples are in MACRO, BLISS, BASIC, FORTRAN and PASCAL both with and without the use of 
LIB$MATCH_COND. Using LIB$MATCH_COND is the preferred method. 

• MACRO 

Without using LIB$MATCH_COND: 


♦ EXTRN LIB_ PROC t LIB__NOSUCHFIL t LIB_NOSUCHDEU t 

LIB_NOSUCHDIR 

CALLG ARGLST t LIB_PROC 


BLBS 

RO t 

1 0$ 

5 

Branch 

if 

success 


CM PL 
BEQL 

RO , 
20$ 

#LIB_ 

-NOSUCHFIL 

? 

Branch 

i f 

no such 

file 

CM PL 
BEQL 

RO , 
30$ 

ttLIB_ 

-NOSUCHDEU 

5 

Branch 

i f 

no such 

device 

CM PL 
BEQL 

RO , 
40$ 

#LIB_ 

-NOSUCHDIR 

! 

Branch 

i f 

no such 

directory 




5 

Here if 

any other 

error 


The same example, using LIB$MATCH_COND: 

♦ EXTRN LIB_PROC t LIB$MATCH-COND * LIB_NOSUCHFIL, 

LIB_NOSUCHDEU > LIB__NOSUCHD I R 


CALLG 

ARGLST , G''LIB-PROC 




BLBS 

RO t 

10$ 

? Branch 


i f 

success 

PUSHAL 

#LIB 

_NOSUCHDIR 





PUSHAL 

#LIB 

_NQSUCHDEU 





PUSHAL 

«LIB 

_NOSUCHFIL 





PUSHL 

RO 






CALLS 

#4 t 

G''LIB$MATCH_ 

COND 




CASEB 

RO * 

#1 , #3 





20$- 15$ 



? No 

such 

file 

30$- 15$ 



? No 

s 

u c h 

device 

40$-40$ 



; No 

5 

u c h 

directory 




5 Here 

i f 

any other 
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• BUSS 


Without using LIB$MATCH_COND: 

EXTERNAL ROUTINE LIB_PROC: ADDRESS ING_MODE (GENERAL) 
EXTERNAL LITERAL LIB__NOSUCHFIL * LIB__NOSUCHDEO * 

LIB_NOSUCHDIR: 

ROUTINE ♦♦♦ 

BEGIN 

LOCAL COND_OAL? 

C 0 N D _ 0 A L = LIB_PROC (...) 

IF NOT ♦ COND_OAL 
THEN 

SELECTONE .COND-OAL OF 
SET 

[LIB_NOSUCHFIL]: ... 5 

CLIB_NOSUCHDEO]: ♦ ♦ ♦ 5 

[LIB_NOSUCHDIR]: ... 5 

[OTHERWISE]: ... 5 

TES ; 

The same example, using LIB$MATCH_COND: 

EXTERNAL ROUTINE 

LIB_PROC: ADDRESS ING_MODE (GENERAL) » 
LIB$MATCH_COND: ADDRESS ING_MODE (GENERAL) 5 
EXTERNAL LITERAL 

LIB_NOSUCHFIL * LIB_NOSUCHDEO, LIB_NOSUCHDIR? 

ROUTINE ... 

BEGIN 

LOCAL COND-UAL 5 
C 0 N D _ U A L = LIB_PROC (...) 

IF NOT *COND_UAL 
THEN 

CASE LIB$MATCH_COND (.COND_UAL, 

'/.REF (LIB_NOSUCHFIL) , 

'/.REF (LIB_NOSUCHDEO) , 

'/. R E F ( L I B_NOSUCHDIR)) FROM 1 TO 3 OF 

SET 

[ 1 ] : ... ? 

[2] : ... 5 

[3] : ... ? 

[OUTRANGE]: ... ? 

TES 5 

• BASIC 

Without using LIB$MATCH_COND: 

ICO EXTERNAL INTEGER FUNCTION LIB_PROC 
200 EXTERNAL INTEGER CONSTANT LIB__NOSUCHFIL t 
LIB__NOSUCHDEO * LIB__NOSUCHDIR 
300 DECLARE INTEGER COND.OAL 
400 C 0 N D _ 0 A L = LIB_PROC (...) 

500 IF ( C0ND_0AL AND 1'/) <> 1'/ THEN 

IF COND_OAL = LIB_NOSUCHFIL THEN 

♦ ♦ ♦ 

ELSE IF COND-UAL = LIB_NOSUCHDIR THEN 

♦ ♦ ♦ 

ELSE IF COND_OAL = LIB_NOSUCHDEO THEN 

ELSE 

GOO 
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The same example, using LIB$MATCH_COND: 


100 EXTERNAL INTEGER FUNCTION LIB_PR0C> 
LIB$MATCH_COND 

200 EXTERNAL INTEGER LIB__NOSUCHFIL * LIB--NOSUCHDEO * 
LIB_NOSUCHDIR 

300 DECLARE INTEGER COND-VAL 
400 COND-OAL = LIB♦PROC( ♦ ♦ * ) 

500 IF (C0N_0AL AND 11) <> 11 THEN 

ON LIB$MATCH_COND(LIB_NOSUCHFFIL # 

LIB — NOSUCHDEU * LIB__NOSUCHDIR) 

GOTO 1000» 2000 * 3000 

1000 

2000 

3000 


• FORTRAN 

Without using LIB$MATCH_COND: 


EXTERNAL LIB_PROC» LIB__NOSUCHFIL» LIB--NOSUCHDEO * 

1LIB_NOSUCHDIR 

INTEGER*4 LIB_PROC, COND-0AL 


♦ 

COND-YAL = LIB-PROC <♦♦.) 


(♦NOT* 

COND-YAL) 

THEN 

IF (COND 

-UAL ♦ EQ ♦ 

7.L0C< 

ELSE IF 

(COND-YAL 

♦ EQ ♦ 

ELSE IF 

(COND-OAL 

♦ EO ♦ 

4 4 * 

ELSE 



END I F 




LIB_NOSUCHFIL)) THEN 

7, L 0 C ( L I B — NOSUCHDEY) ) THEN 
7. L 0 C ( L I B_NOSUCHDIR) ) THEN 


The same example, using LIB$MATCH_COND: 


EXTERNAL LIB-PROC> LIB$MATCH-COND 

EXTERNAL LIB__NOSUCHFIL * LIB--SUCHDEY t LIB_NOSUCHDIR 

INTEGER4 LIB_PROC> LIB$MATCH-COND t COND-YAL 


COND-YAL = LIB_PROC (♦♦♦) 

IF (♦NOT♦ COND-OAL) 

1 GOTO 20 >30 >40 LIB$MATCH-COND<COND-YAL» 

2LIB_NOSUCHFIL * LIB_NOSUCHDEY * LIB_NOSUCHDIR) 


• PASCAL 

Without using LIB$MATCH_COND: 


CONST 

'/.INCLUDE / SYS$LIBRARY : SIGDEF*PAS' 


CASE LIB-PROC ( ♦ . * 

LIB_NOSUCHFIL 

OF 

♦ ♦ ♦ 5 

-c 

N o 

such 

f i 1 e > 

LIB_NOSUCHDEY 

♦ ♦ ♦ 5 

■c 

N o 

such 

device} 

LIB_NOSUCHDIR 

♦ ♦ ♦ 

-c 

N o 

such 

directory} 

OTHERHISE : ♦ . ♦ 


■c 

No 

match 

} 


END ; 
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The same example, using LIB$MATCH_COND: 


FUNCTION LIB$MATCH_COND(A t B *C > D : INTEGER) s INTEGER? 
EXTERN 5 

CONST 

'/.INCLUDE ' S Y S $ L I B R A R Y : SIGDEF*PAS' 

COND.UAL := LIB_PROC ( ♦♦♦ ) 

CASE LIB$MATCH_COND (C0ND_UAL » LIB__NOSUCHFIL t 
LIB_NOSUCHDEU * LIB_NOSUCHDIR) OF 


0 : 

♦ ♦ ♦ 9 

-c 

N o 

match} 

1 : 

♦ ♦ ♦ 9 


No 

such file> 

2 : 

♦ ♦ ♦ ; 

-c 

N o 

such device} 

3 : 

♦ ♦ ♦ 

-c 

N o 

such directory} 


END ? 


5.2 Signaling Error Conditions 

5.2.1 Signaling Exception Condition 

Whenever it is necessary to indicate an exception condition or display a message rather than return a 
status code to the calling program, your procedure should call LIB$SIGNAL. The call to LIB$SIGNAL 
initiates the process of searching the currently active stack frames for a condition handler to handle 
the exception. LIB$SIGNAL scans the stack frame by frame, starting with the most recent frame. 
When LIB$SIGNAL finds a condition handler established for a frame, it invokes it to handle the 
condition. 

The calling sequence for LIB$SIGNAL is: 

CALL LIB$SIGNAL (condition-value [parameters...]) 
condition-value 

A standard signal name designating a VAX-11 system-wide 32—bit condition value (passed by 
immediate value). 

parameters 

Optional additional FAO (formatted ASCII output) parameters for message (passed by immediate 
value). See the VAX-11 Run-Time Library User's Guide or the description of $PUTMSG system 
service in the VAX/VMS System Services Reference Manual for the interpretations of the FAO 
parameters. 

5.2.2 Stop Execution by Signaling 

If you want your procedure to indicate an exception or display a message, but you do not 
want execution to continue, your procedure should call LIB$STOP instead of LIB$SIGNAL. Like 
LIB$SIGNAL, LIB$STOP scans the stack frame by frame, starting with the most recent frame, and calls 
the condition handlers associated with the currently active frames. However, LIB$STOP guarantees 
that control does not return to the program that called it. The calling sequence for LIB$STOP is: 

CALL LIB$STOP (condition-value [parameters...]) 

The LIB$STOP parameters are identical to those described for LIB$SIGNAL. 

The VAX-11 Run-Time Library User's Guide discusses LIB$SIGNAL and LIB$STOP in more detail. 
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5.3 Internal Signaling 

Because you can choose to organize procedures in levels of abstraction (see Section 4.1), some 
procedures might not be available to the calling program across the modular interface. One way to 
solve this problem is to use internal signaling between procedures that are at different levels. 

To use internal signaling, the procedures that can be called across the modular interface must estab¬ 
lish a condition handler. Whenever any of your procedures detect an error, they might call a central 
error-signaling procedure and pass the error number as a parameter to be used in a 32-bit condition 
value (bits 14 through 3). This error-signaling procedure would convert the error number to a 32-bit 
condition value by: 

• Shifting the error number left by 3 bits 

• Inserting a severity code (usually severe = 4) 

• Setting the facility number field (bits 26 to 16) 

• Setting bits 27 and 15 (to specify that this is a user-created condition value) 

The error-signaling procedure then adds any extra arguments and signals the error by calling 
LIB$SIGNAL or LIB$STOP. For example, the FORTRAN support library procedure FOR$$SIGNAL 
adds the current logical unit number and file name to the argument list, followed by the VAX-11 RMS 
condition value and status value from the current FAB or RAB. The $$ indicates that FOR$$SIGNAL is 
an internal interface and is not part of the interface to user programs. 

Your specific condition handler is then entered. It can decide how to proceed from this point. 
Usually, it unwinds to the caller of the establisher (which is the program calling across the modular 
interface). The signaled condition value is the value returned to the calling program that called the 
establisher (outermost layer). This can be done by making LIB$SIG_TO_RET the specific error condi¬ 
tion handler. LIB$SIG_TO_RET can also be called from your handler. 

For example, the condition handler established by the FORTRAN support procedures inserts the 
program counter (PC) of the calling program into the Signal argument list and either: (1) resignals 
or (2) unwinds to the ERR= address if ERR= is specified by the calling program as an optional 
argument. 

The internal signaling procedure FOR$$SIGNAL does not know the PC of the calling program. 
However, it is easy for the handler to find it, since the handler is passed the address of the stack frame 
of the establisher (which contains the PC of the calling program). 

5.4 Creating a Procedure Activation Environment 

You can use the VAX/VMS error-signaling mechanism to create a special activation environment for 
each procedure. This is needed to implement most higher-level languages. In such cases, the com¬ 
piled code for each procedure activation establishes a language-specific condition handler. The 
address of the handler (stored in longword zero of the stack frame) can also serve as a way to identify 
in which language the procedure was written. This is useful for language support procedures that 
need to know the layout of the stack frame. 

Such a handler takes appropriate language-specific action on software errors signaled by mathematics 
(MTH), string (STR), or language support (BAS, FOR, PAS) procedures, or by hardware errors. By 
using such a per-activation mechanism, procedures of different languages can call one another, each 
with its own environment. 
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Note that the main program is also a procedure and follows the same per-procedure activation 
technique. Furthermore, the code generated by the main program must not call a language initializa¬ 
tion routine, since the main program might call procedures written in any language. Alternately, a 
subroutine written in a particular language cannot depend on the main program being written in the 
same language. Hence, the subroutine cannot depend on a particular main program initialization 
code having been called. 
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Chapter 6 

Coding Modular AST-Reentrant Procedures 


This chapter describes coding techniques for modular procedures that use the VAX/VMS AST 
(asynchronous system trap) interrupt mechanism, or permit calling programs to use it. A procedure is 
AST-reentrant if it: 

• Can be interrupted between any two instructions, permitting it or any related procedure to be called 
(reentered) 

• Executes correctly when continued 
This chapter describes: 

• How to code AST-reentrant procedures 

• How to code I/O that may or may not be at the AST level 

All modular procedures should be AST-reentrant so they can be called from any program. If your 
procedure is not AST-reentrant or calls any procedure that is not, your program documentation 
should relate this to warn others against using your procedure. 

Note 

Do not confuse the term AST—reentrant with reentrant , which refers to a more restric¬ 
tive set of conditions encountered when static storage is shared between processes. In 
such a situation, there can be more than two threads of concurrent execution, and 
each thread can alternately progress toward an end. The restrictions become even 
more severe if the processes can be executing simultaneously on several processors. 

Since most modular procedures share code (and not data) between processes, not all 
of the techniques described in this chapter are applicable to reentrant procedures on 
single or multiprocessor configurations that share data between processes. All of the 
techniques in this chapter assume that data is statically allocated per-process. 
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6.1 AST Interrupts in a Process 

Some VAX/VMS system services let an event interrupt a process. Since the interrupt occurs out of 
sequence with respect to process execution, the interrupt mechanism is called an asynchronous 
system trap (AST). An AST interrupt transfers control to a user-specified routine that services the event. 
The AST routine can call other procedures, including library procedures. The AST routine and any 
procedures it calls are said to be executing at AST level. 

While at AST level, a process cannot be re-interrupted at the same access mode. The process runs to 
completion at the AST level before the non-AST level procedure resumes and can execute another 
instruction. Hence, a process is either executing at AST level or at non-AST level, and thus consists of 
two "threads of execution," one thread at each level. 

Note 

The AST level cannot stall or use "busy wait" to avoid being called before the 
non-AST level is out of a critical section of code. 

When the AST routine finishes servicing the event, it returns control to its caller (VMS). This automat¬ 
ically continues execution of the interrupted procedure at the point of interruption. 

For example, you could call the Set Timer system service ($SETIMR) that would specify the address of 
an AST level procedure to be executed after a specified amount of time has elapsed. At the required 
time, the system generates an AST interrupt by stopping the currently executing procedure and calling 
the specified AST routine. Another example of an AST event is typing CTRL/C on the terminal. 

For information on the implementation of AST interrupts by system services, see the VAX/VMS System 
Service Reference Manual. 

6.1.1 Using AST Routines 

To use AST interrupts, you must write an AST routine to take control at AST level. An AST routine 
must follow these guidelines: 

• It must be separate from the currently executing procedure. 

• It must not modify data or instructions used by the interrupted procedure or its callers. 

• It is called with a CALLG instruction. 

• If it modifies any registers other than RO and R1, it must set bits in the entry mask to save the 
contents of the registers. 

• If it calls any other procedures, they must all be AST—reentrant. 

• It must return to its caller with a RET instruction. 

6.1.2 Interrupting a Non-AST-Reentrant Procedure 

If an AST interrupt occurs during the execution of a procedure that is not AST-reentrant, you can get 
unpredictable results from either the AST—level procedure or the interrupted procedure. 

BASIC procedures can be made AST—reentrant since local variables are allocated on the stack. Avoid 
use of static storage by not using COMMON (COM) and built-in functions that have static storage. 
These include STATUS, CTRLC, RCTRLC, DET, FIELD, NUM, NUM2, ON ERROR GO TO, 
RESUME, and RECOUNT. You should also avoid the SYS functions ASSIGN, DEASSIGN, message 
send and receive. 
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A nontrivial FORTRAN procedure cannot be made AST-reentrant. Hence, FORTRAN procedures can 
be called only at the AST level or the non-AST level, but not both. 

PASCAL procedures can be made AST—reentrant since local variables are allocated on the stack. 
Avoid use of static storage by not declaring variables at the program or module level. 

6.2 Writing AST-Reentrant Modular Procedures 

You must observe the following rules when writing AST-reentrant procedures: 

• Only AST-reentrant procedures can be called at both the AST and the non—AST level. Since an AST 
interrupt can arrive at any time, AST—reentrant procedures must be written so that an AST interrupt 
can occur between any two instructions without interfering with the correct operation at either the 
AST or non—AST level. If a single instruction is interruptible, an AST interrupt can also occur within 
that instruction. (For more information, see the VAX Architecture Handbook.) 

• An AST-reentrant procedure cannot call any non-AST reentrant procedures. 

• If both an AST level and a non-AST level procedure concurrently access data in static storage, each 
procedure must make sure that race condition interference does not occur. (See Section 6.4.) 

Note 

The term race condition refers to a situation where two independently executing 
threads of execution can access the same data in a conflicting manner. A race 
condition exists, for example, if a single instance of a process-wide resource can be 
allocated to different procedures at both the AST and non-AST level. 

• If I /O at the AST level is performed, you should avoid simultaneous I /O of the same data from both 
AST and non-AST level procedures. (See Section 6.4.) 

A procedure that has no static storage and calls no other procedures is automatically AST-reentrant. 
A procedure that has no static storage and only calls other AST-reentrant procedures is also AST- 
reentrant. To ensure that a procedure is AST-reentrant, it should use only stack and /or heap storage. 

A procedure that uses static storage can be AST-reentrant, although this is difficult to program since 
you could be changing statically allocated data when the interrupt occurs. 

6.3 Eliminating Race Conditions During Concurrent Access 

There are a number of ways for your procedure to eliminate conflict when accessing and modifying 
data in its static storage: 

• Perform all accessing or modification in a single uninterruptible instruction. 

• Detect concurrency of access to data using "test and set" instructions at entry to and exit from data 
storage. 

• Keep a call-in-progress count that is incremented when your procedure is called and decremented 
when it returns. The count is used as an index into separate allocated areas. 

• Disable AST interrupts upon entry and restore the enable state on exit. 

The following sections describe these methods. 
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6.3.1 Performing All Accesses in One Instruction 


For some applications, all data modification in static storage can be performed in a single uninterrupt¬ 
ible instruction. For example, you can use queue instructions at the beginning and end of your 
procedure to control resource allocation. 

The remove queue instruction removes a control block (containing an instance of a process-wide 
resource) from the free list of available resources, making the resource available to the program. The 
insert queue instruction places the control block back in the free list when the program no longer 
needs the resource. 

The queue headers are allocated in static storage. The control blocks themselves can be in static 
storage (if a specific number of resources are needed) or in dynamic heap storage (if a variable 
number of resources are needed). 

For example, STR$COPY allocates and deallocates string space in heap storage. A fixed number of 
queue headers are allocated in static storage — one queue for each string length. 

The following example illustrates an AST-reentrant procedure that uses queue instructions to control 
allocation of quadword blocks: 



♦ PSECT 

-LIB-DATA PIC # USR # CON 

#REL 

♦ LCL# N0SHR# N 0 E X E#RD#WRT 

FLAG: 

♦ LONG 

0 

5 

First-time flag 

Q_HED 

♦ LONG 

0 >0 




♦ PSECT 

-LIB_C0DE PIC # USR # CON 

# REL 

# LCL#SHR # EXE *RD# N0WRT 


♦ENTRY 

LIB-GET-X # A M<> 




BBC 

FLAG # FIRST 

5 

Branch on 1st call only 

TRY : 

REMQUE 

@Q_HED* rO 

5 

R 0 = address of queue 


BOS 

10$ 

5 

Branch if empty and fill 


RET 




10$: 

BSBB 

FILL 

5 

Fill queues 


BRB 

TRY 

5 

Try again 

? He re 

o n first 

call only 



FIRST: 

$SET AST 

#0 

5 

Disable A S T s # R0 = o1d setting 


BBSS 

FLAG # 20$ 

5 

Branch if already set 


M00AL 

Q_HED # Q-HED 

5 

M a ke queue e mpt y 


M00AL 

Q-HED # Q-HED + 4 

? 

BacK pointer too 


BSBB 

FILL 

5 

Fill queues 

20$ : 

CM PL 

#SS$_WASSET# R0 

5 

w e r e A S T s enabled before? 


BNEQ 

TRY 

! 

No# leave disabled# retry 


$SET AST 

1 

5 

Yes# enable A S T s 


BRB 

TRY 

5 

Try again 

FILL: 

Set space for 10 q uadwo rds by 

calling LIB$GET_0M 


and insert in queue using INS0UE 



RSB 





Note 

The above example could be recoded using REMQHI and INSQHI and avoid the need 
to have a first time flag. This is because an empty queue is represented as zero entries 
for the interlocked, self-relative queue instructions. 
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In some applications, the static storage is divided into two or more sections, each section in a queue. 

You can use a single queue instruction at the beginning of your procedure to remove one section, and 
another can be used at the end to insert the section back in the queue. 

While a section is removed from the queue, your procedure can modify data in it. If an AST-interrupt 
occurs while the section is removed, a different section of data is used instead, thus avoiding conflicts 
with the interrupted procedure. 


6.3.2 Using “Test and Set” Instructions 

To detect concurrent access of static storage at both AST and non-AST levels, you should add the 
following steps to your procedures: 

• Place a branch on bit set and then set instruction (BBSS) immediately before each of your proce¬ 
dures accesses static storage. 

• Access and/or modify static storage. 

• Place a branch on bit clear and then clear instruction (BBCC) immediately after each of your 
procedures has completed access to static storage. 

The BBSS instruction detects that a concurrency conflict is about to take place before static storage 
has been accessed. There are two alternate techniques for resolving concurrency conflicts detected 
by the BBSS and BBCC instructions: 

• Use separate, statically allocated areas at the AST and non—AST levels. When the BBSS instruction 
detects concurrency at the beginning, use the second allocated area. Note that this technique does 
not work if an exception condition occurs between execution of the BBSS instruction and the BBCC 
instruction or if your procedure has not established a condition handler. This is because a condition 
handler established by the calling program might also simultaneously call your procedure. 

• Reexecute your procedure if concurrency is detected at the end. When the BBCC instruction 
detects this concurrency, branch back to the beginning of your procedure and try again. 

The following example illustrates the latter technique. This MACRO procedure, LIB_GET_JNUM, 
allocates and deallocates identifying numbers: 


♦TITLE 

LIB_GET 

_ I NUM -- Allocate 

TAB : 

♦ UORD 

0 


♦ENTRY 

LIB_GET_INUM t A M< 

10$ : 

FFC 

« 1 * ** 1 0 * T A B * R 0 


BEQ 

20$ 


BBSS 

R0 * TAB t 10$ 


M00L 

R0 * @4(AP) 


MOVL 

RET 

#1 * R0 

20$: 

CLRL 

@4( AP) 


CLRL 

RET 

R0 


♦ END 


arid deallocate id* nos* 1 - 10 

5 Bitmap for f 1 a 3 s 

5 Find first free id* no* 

5 Branch if none free 
5 Indicate id* no* in use 
5 Return id* no* f o u n d 
5 Indicate success 


5 R e t u r n 0 
5 Indicate failure 
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6.3.3 Keeping a Call-in-Progress Count 

If the data base is to be kept separate between calls, you can keep track of when your procedure is 
called by using a call-in-progress count. Before data base access, the count is incremented and used 
to index into a table of addresses for the separate data bases. You should check for a count that 
exceeds the table length. After the data base has been accessed, the count is decremented. 

This technique has an advantage over the BBxx technique because it can handle more than two levels 
of reentrance. However, it is less reliable, since an exception can cause the count never to be 
decremented, leading to an eventual procedure malfunction. You can avoid this by establishing a 
condition handler in your procedure. 

6.3.4 Disabling AST Interrupts 

Sometimes the only way to avoid race conditions is to disable AST interrupts during the access to 
static storage and restore the state of the AST enable at the end. However, this technique could 
adversely affect performance of real-time programs using AST interrupts. Therefore, you should avoid 
disabling AST interrupts whenever you can use any technique described in Sections 6.3.1 to 6.3.3. 

Try to minimize the number of instructions during which the AST interrupts are disabled. Before 
disabling AST interrupts, establish a condition handler to restore the AST level in case an exception or 
stack unwind occurs. 

The following BLISS example disables ASTs and then restores the state of the enable before returning 
to its caller: 

GLOBAL 

STR$$V_INIT : INITIAL (0) 

BEGIN 

LOCAL 

AST_ST ATUS5 

! + 

! Disable ASTs so we can test S T R $ $ 0 _ INIT♦ We must not permit an 
! AST after we start to initialize the queues* 

AST_STATUS = $SETAST(ENBFLG = 0) 

IF (NOT ♦STR$$V_INIT) 

THEN 

BEGIN 

! + 

! We must do the initialization* 


MarK the initialization as complete* 

BLOCK CSTR$$V_INIT t0*0t 1 *01 = 13 

END ; 

If ASTs were enabled when we entered * re-enable them* 

IF ( *AST_STATUS EQL SS$_WASSET> THEN $SET AST (ENBFLG = 1)5 

RETURN 5 
END 5 
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6.4 Performing I/O at the AST Level 

If your procedure performs I/O using VAX—11 RMS system services, there are several coding tech¬ 
niques you must observe for your procedure to be AST-reentrant: 

• When opening process-permanent files such as SYS$INPUT, SYS$OUTPUT, SYS$COMMAND, or 
SYS$ERROR, check for the VAX-11 RMS error status RMS$_ACT (Active) after each $CREATE or 
$OPEN service. This error indicates that a record operation had already started for the process- 
permanent file. The error does not occur for non-process-permanent files, and the $OPEN service 
follows the constraints of shared access to the file that may have been imposed by a previous 
$OPEN service. If the error occurs, try the $CREATE or $OPEN service again. Repeat this until it 
succeeds. 

• When performing record I/O to any type of file, check for the RMS error status RMS$_RSA (record 
stream active) after each $GET and $PUT service. This error indicates that a record operation had 
already been started for the file. If the error occurs, perform a $WAIT using the same record block 
(RAB). When control returns to your procedure, try the $GET or $PUT service again. Repeat this 
procedure until it succeeds. 

The BASIC and FORTRAN I/O support procedures use this technique to perform I/O at AST and 
non-AST level. The VAX/VMS Put Message system service($PUTMSG) also uses this technique so 
an error message signaled at AST level will be output on SYS$OUTPUT even though the non-AST 
level is also calling $PUT. 

• Avoid storing data in a record access block (RAB) that VAX—11 RMS could still be accessing. Your 
procedure can do this in two ways: 

- Allocate the RAB on the stack so AST and non-AST level have separate RABs. 

- Allocate RAB in static storage along with a busy bit. The busy bit is tested and set using a BBSS 
instruction before the RAB is accessed. If the RAB is already busy, your procedure executes a 
$WAIT using that RAB. 

For synchronous I/O (I/O that is always completed before returning control to your procedure), 
you can allocate the RAB in either of these ways. However, the first is more reliable, since it has no 
static storage and hence cannot behave erroneously if an exception is signaled. 

For asynchronous I/O (when control is returned to your procedure before I/O is completed), you 
must use the second technique. 
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Chapter 7 

Building Modular Procedure Libraries 


Modular procedure libraries consist of compiled and assembled object code intended to be associ¬ 
ated with a calling program at link time. References to procedures in these libraries are resolved when 
the linker searches the user libraries specified in the LINK command or the default system libraries. 
The program can then call library procedures at run time. 

DIGITAL supplies several procedure libraries, such as the VAX—11 Common Run-Time Procedure 
Library (also called the Run-Time Library), that support components of VAX/VMS. You can explicitly 
access the procedures in the Run-Time Library to perform frequently used operations. To do this, 
simply include calls to Run-Time Library procedures in your program. The linker automatically 
searches the default libraries to resolve references to Run-Time Library procedures. See Section 1.2. 

You can create your own procedure libraries and shareable images by following the guidelines in 
Section 7.1. Section 7.2 shows you how to use transfer vectors to make your shareable images easier 
to maintain. Before you begin grouping modular procedures, make sure they conform to the rules 
listed in Appendix A. 

7.1 Grouping Procedures into Libraries 

There are three ways to group modular procedures: 

1. Combine object modules into an object module library. 

2. Link object modules together into a shareable image. 

3. Combine shareable images into a shareable image library. 

The following sections show how to create and install these three types of procedure libraries, and 
how to access them when you link and run a program. 

7.1.1 Creating and Installing an Object Module Library 

You can create your own object module library, which can contain object files produced by any 
VAX—11 language compiler. The LIBRARY command creates an object module library from a set of 
object files. 

After compiling the programs, use the LIBRARY command to create an object library from the object 
files. The LIBRARY command for building a user-created object library has the following general 
form: 

$ LIBRARY /CREATE library-name file-spec[,...] 
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where: 


library-name 

is the name you have given the library. The default file extension for library-name is .OLB. 
file-spec 

is the name of an object file. The default extension for file-spec is .OBJ. 

The remainder of this chapter shows the creation of a sample user-created object module library 
called GRAPHICS.OLB. This library contains the modules GRASPHERE.OBJ and GRACUBE.OBJ. The 
library facility code used is GRA. Assume that these modular procedures produce mathematical 
representations of circles, cylinders, squares, and other geometric shapes. For example, the module 
GRASPHERE.OBJ might contain several related procedures that create spheres (GRA—SPHERE), oblate 
spheroids (GRA_OBI—SPH), and spherical sections (GRA_SPH_SEC) grouped because they share 
similar code. The module GRACUBE.OBJ could contain a procedure that generates cube shapes. The 
following command creates the object module library from the set of object files: 

$ LIBRARY /CREATE GRAPHICS GRASPHERE tGRACUBE 

After this command is given, GRAPHICS.OLB is ready to be linked with an application program (see 
Section 7.1.5). 

Figure 7-1 shows the development of the user-created library of graphics procedures, called 
GRAPHICS.OLB. 

Figure 7-1: Development of a User-Created Object Module Library 
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7.1.2 Creating and Installing a Shareable Image 

If a module is going to be used frequently by many processes, it is generally more convenient to 
include the module in a shareable image. Linking a procedure as a shareable image gives you the 
following advantages: 

• Conserves disk storage space 

• Reduces paging I/O 

• Saves memory at run time 

• Shortens link time, since a shared library has already passed through the linker 

The disadvantage of using a shareable image is that it increases the size of the process address space. 

Observe these guidelines when deciding whether to create a shareable image: 

• The combined code of all procedures in the planned shareable image should be at least 10K bytes. 

• The number of potential simultaneous users for these procedures should be three or more. 

When you place a module in a shareable image, you should also place it in an object module library. 
Then you can extract a particular module. Also, if a program becomes large enough to approach your 
system's virtual memory limit, you can copy called modules from the object library rather than 
allocate virtual memory for the entire shareable image. 

A shareable image can be built from either position-independent or non-position-independent code. 
However, it is recommended that your shareable image be written in position-independent code. 
Further, you should provide transfer vectors to access it from calling programs (see Section 7.2). If 
your shareable image uses position-independent code and transfer vectors, you can install a new 
version of the shareable image without relinking the images that call it. You can update any shareable 
image that you have created, but when you add or modify code in a shareable image, you must 
reinstall the entire image. 

The linker and image activator treat shareable images as follows: 

1. The linker allocates virtual memory for position-dependent shareable images. 

2. Position-independent shareable images are allocated at run time at higher addresses. 

If you are installing a based shareable image, there are some restrictions. See the VAX—11 Linker 
Reference Manual. 

To create a shareable image from an object file, use the /SHAREABLE qualifier with the LINK 
command: 

$ LINK /SHAREABLE file-spec 

The default file type for file-spec is .OBJ. The default file type for the resulting shareable image 
is .EXE. 


Building Modular Procedure Libraries 


7-3 




Figure 7-2 shows the transformation of the library GRAPHICS from an object module library to a 
shareable image. To do this, you must create a command procedure (MAKESHAR.COM in Figure 
7-2) to build the shareable image. For example: 

$ LINK/SHAREABLE = GRAPH ICS/MAP/FULL- 

GRAPHICS/INCLUDE = <GRA_SPHERE »♦♦♦)> MAKESHAR/0PTIONS 
where: 

/SHAREABLE instructs the linker to build a shareable image called GRAPHICS.EXE. 

/MAP/FULL produces a detailed map of the image in (default) GRAPHICS.MAP. 

/INCLUDE specifies the list of objects to be taken from GRAPHICS.OLB for inclusion in this 

shareable image. 

MAKESHAR.OPT is an optional input file that provides additional information to the linker, such 
as the creation of transfer vectors, and the specification of the GSMATCH 
option. For example, MAKESHAR.OPT may contain the following: 

CLUSTER=TRANS_VEC * > »GRAVECTOR 
GSMATCH=LEQUAL>1>0 

The GSMATCH option is strongly recommended when you are creating share¬ 
able images. For more information on option files, see VAX—11 Linker Reference 
Manual. 

You can optionally install your shareable image as a permanent global section. To do this, refer to the 
VAX/VMS System Manager's Guide. 

Figure 7-2: Creating a Shareable Image 
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7.1.3 Creating a Shareable Image Library 


You can also group shareable images into a library. This allows you to access a number of shareable 
images by simply naming a library in the LINK command. A shareable image library is a symbol table 
that lists the names of a set of shareable images. When you include the name of the shareable image 
library in the LINK command, the linker searches the symbol table to find the required shareable 
images. The linker then reserves address space only for those shareable images that resolve refer¬ 
ences. The required modules will be executed at run time. 

To create a shareable image library, use the LIBRARY command with the CREATE and SHARE 
qualifiers, as follows: 

$ LIBRARY /CREATE /SHARE library-name, file-spec[,...] 

where: 

library-name 

is the name you have given the library. The default file extension for library-name is .OLB. 
file-spec 

is the name of a shareable image. The default extension for file-spec is .EXE. 

7.1.4 Accessing a User-Created Shareable Image 

You cannot run a shareable image. It is incorporated into the executable image of another program by 
the linker. In order to include a shareable image as input to the linker, you must: 

1. Create an options file that contains the name of the shareable image with the file qualifier 
/SHAREABLE. This qualifier causes the program's executable image to contain the name of the 
shareable image. The shareable image is then mapped into the executable image at run time. If 
you want the module to be copied into the program's executable image, specify 
/SHAREABLE = COPY. This is not recommended, however, since it increases the size of the 
executable image by the size of the shareable image. 

2. Include the options file in the LINK command, along with the /OPTIONS command qualifier. 

For example, assume that an application program CARTOON.FOR accesses the shareable image 
GRAPHICS.EXE. To access GRAPHICS.EXE, perform the following steps: 

1. Create an OPTIONS file, NOWSHARE.OPT, which includes: 

GRAPHICS/SHAREABLE 

2. Link the program with the shareable image: 

$ LINK CARTOON, NOWSHARE/0PTIONS 

This command produces CARTOON.EXE, the application program's executable image. 
CARTOON.EXE can now call GRAPHICS.EXE at run time. 

Figure 7-3 illustrates this example. 
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Figure 7-3: Accessing a User-Created Shareable Image 



7.1.5 Accessing a User-Created Library 

Once you have placed module in an object module library or a shareable image library, you can 
include these modules in an executable image. When you specify a library as input to the linker, the 
linker performs the following operations: 

• It processes all input files, including libraries, in the sequence in which you name them. 

• If you specify both the /LIBRARY and /INCLUDE qualifiers after a library file specification, the 
linker includes the named module first and then, if necessary, searches the library. 

• After it has processed all named input files, including your libraries, it searches the default share¬ 
able image library (IMAGELIB.OLB) and the default object module library (STARLET.OLB) for 
unresolved references. 

Thus you can include modules in an executable image either implicitly, by naming the library where 
they can be found, or explicitly, by using the /INCLUDE qualifier. Further, if your program calls a 
procedure, such as a Run-Time Library procedure, that is defined in one of the default libraries, the 
procedure is automatically included. 

The example of the graphics library will illustrate the use of object module libraries and shareable 
image libraries. 

To access the modules in the object module library GRAPHICS.OLB, use the following form of the 
LINK command: 

$ LINK CARTOON * GRAPH ICS/LIBRARY 

Assume that you have transformed the object module library GRAPHICS.OLB into a shareable image 
library called GRAPH-SHARE.OLB. You use the same format to link the program to the shareable 
image library: 

$ LINK CARTOON * GRAPH-SHARE/LIBRARY 
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The linker automatically searches GRAPHICS.OLB or GRAPH-SHARE.OLB to resolve references 
from CARTOON, before searching IMAGELIB.OLB and STARLET.OLB. 

You can specify a combination of shareable images and libraries in the LINK command. Assume, for 
example, that you type: 

$ LINK CARTOON * LIBOPT/OPTIONS t GRAPHICS/LIBRARY * GRAPH_SHARE/LIBRARY 
The following operations are performed: 

1. The VAX-11 Linker links CARTOON.OBJ into the image. 

2. LIBOPT.OPT contains the command CIRCLE/SHAREABLE. This specifies your shareable image, 
CIRCLE.EXE, as input to the linker. The linker resolves references using this image and creates 
linkages to it. 

3. The linker searches GRAPHICS.OLB, the user-created object module library. When the linker 
finds a module in which a reference is resolved, it copies the module into the image. 

4. The linker searches GRAPH-SHARE.OLB, the user-created shareable image library. When the 
linker finds a module in which a reference is resolved, it creates linkages to the module. 

5. The linker automatically includes IMAGELIB.OLB, the default shareable image library, if and 
only if it resolves any remaining unresolved references. 

6. The linker automatically searches STARLET.OLB, the default object module library, if any unre¬ 
solved references remain. If modules in STARLET.OLB resolve any of those references, the linker 
copies them into the image. 

You can change the default searching operation of the linker by specifying the qualifiers /NOSYSSHR 
or /NOSYSLIB in the LINK command. See Section 1.2. 

The executable image that results from these steps can be executed in your process with the 
RUN command: 

$ RUN CARTOON 

This command executes CARTOON.EXE and all the modular procedures that it calls, including 
CIRCLE.EXE, any called modules from GRAPHICS.OLB or GRAPH—SHARE.OLB, and any implicitly 
called modules from the VAX-11 Run-Time Library. 

Figure 7-4 shows how the command line discussed here links shareable images and libraries to a 
program object module to form an executable image. Figure 7—5 shows what happens when the 
program is executed. 

Note that the modules taken from STARLET.OLB and GRAPHICS.OLB are copied into each image 
that links with the object libraries. On the other hand, only one copy exists of each shareable module 
in IMAGELIB.OLB, GRAPH-SHARE.OLB, and CIRCLE.EXE. These shareable modules reside in sepa¬ 
rate image files shared between processes at run time. 
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Figure 7-4: Linking Programs to Run-Time Libraries 
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Figure 7-5: Executing an Image That Calls Library Procedures 

























7.2 Creating and Using Transfer Vectors 

A transfer vector is a labeled virtual memory location that contains an address of, or a displacement 
to, a second location in virtual memory. This second location is the start of the actual instruction 
stream that receives control. When you use transfer vectors to locate shareable images, the vectors 
are normally displacements rather than actual virtual addresses, so that the code remains position- 
independent. There are two reasons for using transfer vectors to reference shareable images: 

• Transfer vectors make it easy to modify and enhance the contents of the shareable image. 

• Transfer vectors let you avoid relinking other programs bound to the shareable image. 

7.2.1 Building Transfer Vectors 

Transfer vectors must be written in MACRO; however, they can be used with procedures written in 
any language. The CALLS or CALLG instruction transfer vector has the form: 

♦TRANSFER fac.svwbol 5 B e 3 i n transfer vector to library 

5 entry point » fac_symbol 

♦MASK fac.symbol 5 Store register save mask 

J M P A f a c _ s y m b o1+ 2 ? Branch to routine at instruction 

5 beyond the register save mask 

The JSB instruction transfer vector has the form: 

♦ TRANSFER fac.symbol: : 

JMP A fac.symbol 5 Branch to JSB routine 

In these examples, fac—symbol is the procedure's entry point name. For more information on how 
transfer vectors work, see the VAX-11 Linker Reference Manual. 

7.2.2 Using Transfer Vectors 

The linker automatically uses transfer vectors if they are present. Regardless of the procedures' 
languages, code the transfer vectors as shown in Section 7.2.1. Then assemble the program contain¬ 
ing the transfer vectors. The resulting object module is used as input to the linker when you create the 
shareable image with the LINK/SHAREABLE command. The linker binds together the object module 
that contains the transfer vectors and the object module that is being transformed into a shareable 
image. In order to insure that the transfer vector comes first in the shareable image, use an options file 
to specify the transfer vectors. For example, the shareable image GRAPF1ICS, shown in Section 
13.3.2, might be produced with the following command: 

$ LINK/SHAREABLE = GRAPHICS/MAP/FULL GRAPH I CS/INCLUDE=( ♦ ♦ ♦ ) , MAKESHARE/0PTIONS 
where: 

MAKESHARE.OPT is an options file containing the following commands: 

CLUSTER = TRANSFER > > >TRANSVEC 
GSMATCH=LEQUAL *1 *0 

TRANSVEC is the object module containing transfer vectors to all routines in the shareable 

image. 
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The command line causes the linker to add the transfer vector to the shareable image 
(GRAPHICS.EXE) being created. At run time, control passes to the tranfer vector, which in turn uses a 
displacement to pass control to the actual procedure. 

For more detailed information and complete examples, see the VAX—7 7 Linker Reference Manual . 
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Appendix A 

VAX-11 Modular Programming Standard 


This appendix is the VAX-11 standard for writing modular procedures in any language, including 
MACRO and BLISS. This standard is the minimum necessary to interface your software at the callable 
procedure level with software written by others, and vice versa. 

The standard contains required, optional, and recommended elements. Optional elements are indi¬ 
cated by asterisks (*). Non-conformance to optional elements must be indicated in the procedure's 
documentation. Recommendations are described in Section A—7. Non-conformance to recommenda¬ 
tions need not be documented since modularity is not affected. Each element of the standard is 
described in greater detail in other sections of this manual, indicated by parenthesized references. 

Most of this standard was derived by asking: "What general agreements are necessary between 
programmers to permit procedures to execute as expected when combined in arbitrary ways to form a 
program?" 

This means that a procedure not following this standard could cause another modular procedure in 
the program image to execute incorrectly, or vice versa. 

The arbitrary ways of combining procedures are: 

• Your procedure calls other procedures. 

• Other procedures call your procedure. 

• A calling program calls either of the above. 

Therefore, any modular procedure can be added to a collection of modular procedures without 
conflicting with them or those that might be added in the future. 

A.1 Scope of Applicability 

The required, optional, and recommended elements of this standard apply to library procedures and 
are recommended for other types of software, including utilities and application programs. Each 
programming language implemented on VAX lets you write your procedures to explicitly or implicitly 
follow the required elements of the standard for important language features. Therefore, compiler 
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generated code for main programs and externally available subroutines and functions let you follow 
required elements of the standard. Furthermore, the language support procedures conform to the 
required, optional, and recommended elements, except as noted in Section A.3. 

This standard applies to procedures that interface to a calling program; it does not apply to intra¬ 
module or inter-module calls that do not interface to the calling program as long as the entire set of 
procedures follows the standard. 

A.2 Facility-Independent Part of the Standard 

The following required and optional elements of the standard pertain to all facilities, whether in a 
library or not: 

1. Calls to procedures follow the VAX—11 Procedure Calling Standard. (See Appendix C of the 
VAX-11 Run-Time Library Reference Manual.) Some elements of this standard restrict procedures 
to a subset of the VAX—11 Procedure Calling Standard to increase the ability for procedures to 
call one another. 

2. A procedure does not accept data from or return data to the calling program using implicit 
overlaid PSECTs (COMMON in BASIC and FORTRAN, program or module level data in PASCAL) 
or implicit global data areas. Instead, all parameters accepted from or returned to the calling 
program use the argument list and function value registers (RO and R0/R1). (See Section 2.3.1 
and the VAX-11 Procedure Calling Standard.) 

3. Modules must be relocatable. (See Section 4.2.1.) 

4. Procedure entry point names contain at most 31 characters having the following forms: fac$name 
for DIGITAL—supplied procedures, and fac_name for user-supplied procedures, where fac can be 
LIB, MTH, OTS, STR, BLI, BAS, COB, FOR, PAS, or any other language abbreviation (and file 
type) or facility name. 

Global entry point names not intended for use by the calling program have two dollar signs ($$) 

or three underlines (_), respectively. The three underlines are needed to avoid conflict with 

user-defined condition value symbols that have two underlines. If alternate JSB entry points are 
provided, the name ends in _Rn (or just n if name would exceed 15 characters), where n 
indicates the highest register modified or used as an input parameter. 

5. Generally each module contains a single procedure available to a calling program. This permits 
the greatest flexibility in linking procedures to form programs. Procedures can be grouped into a 
single module if they: (1) share the same static storage or (2) have a similar calling sequence, 
perform similar functions, and share a significant amount of code. (See Section 4.1.2.) 

6. The form for module names is the same as that for procedure entry point names to avoid conflict 
when inserted into a library by the LIBRARY command. Modules containing one procedure have 
the same name as that procedure. Modules containing more than one procedure have a name 
formed from a combination or common subset of the entry point names. (See Section 4.2.2.) 

7. Position-independent references (in a module) to writable data PSECTs use longword relative 
addressing. This is done so the VAX—11 Linker can correctly allocate the data PSECT anywhere 
with respect to the code PSECT no matter how many code modules are included. (See Section 
4.2.3.) 

8. External references use general-mode addressing so any of the referenced procedures can be put 
in a shareable image without requiring changes to the calling program. 
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9. A procedure does not print error or informational messages either directly or by calling the 
SPUTMSG system service. Instead, it either returns a condition value in RO as a function value, or 
calls LIB$SIGNAL or LIB$STOP, directly or indirectly, to output all messages. (See Sections 5.1, 
5.2, and A.3.) 

10. If an error condition associated with a file is signaled, the expanded or resultant file name is 
included as one of the FAO arguments in the signal argument list. (See Section 5.2.) 

11. If a procedure requires initialization once for each image activation, it is done without the caller's 
knowledge by: (1) initializing at compile time, or (2) initializing at link time or (3) testing and 
setting a statically allocated first-time flag on each call, or (4) adding a dispatch address to PSECT 
LIB$INITIALIZE. (See Section 4.3.) 

Using LIB$INITIALIZE is not recommended since your procedure cannot be placed in a shareable 
image. Furthermore, a procedure must not use LIB$INITIALIZE to establish a condition handler 
before the main program is called if its action might conflict with that of other condition handlers 
established before the main program. 

12. If a procedure uses a process-wide resource, it calls the appropriate resource allocating library 
procedure or system service to allocate the resource to avoid conflict with allocations made to 
other procedures. To conserve resources, a procedure that requests resource allocation: 

• Calls the deallocation procedure before returning to the calling program, or 

• Remembers the allocation in static storage and calls the deallocation procedure later, or 

• Passes the responsibility for deallocation back to the calling program, or 

• Allocates a fixed number of the resources independent of the number of times it is called 
There are currently resource allocating and deallocating library procedures for: 

• Virtual memory in the program region 

• BASIC/FORTRAN logical unit numbers 

• Process-local event flags 

• Dynamic string memory 

(See Section 4.4 and the VAX—7 7 Run-Time Library User's Guide.) 

13. For each input and output string parameter (or string function value) the calling program either: 
(1) allocates a descriptor, or (2) passes along the address of a descriptor that had been passed to 
it. A procedure accesses a formal string parameter passed to it by: 

• Accessing the string's descriptor indirectly using the argument pointer (AP), or 

• Copying the address of the string descriptor, or 

• Copying the entire descriptor and changing the descriptor class code (in the copy only) to be 
fixed length (DSC$B_CLASS = 1), since there can only be one dynamic string descriptor per 
string (least preferred) 

Note 

The term "formal parameter" refers to the parameter's name as it is known to 
the called procedure, as opposed to either its actual value or its name as it is 
known to the calling program. 
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The three semantics for writing formal string parameters are: 

• Fixed-length string semantics: The formal string is written with space filling or truncation on the 
right using the starting address and length specified in the descriptor passed by the calling 
program. Thus, the entire area described by the string is written. The descriptor is not modified. 

• Varying-length string semantics: The formal string is written with space filling or truncation on 
the right. The descriptor specifies the address of the CURLEN field in the string, a two-byte area 
preceding the text of the string, and the MAXSTRLEN, which represents its maximum length. 
The CURLEN field is modified when the number of characters in the string changes; the 
MAXSTRLEN field does not change. 

• Dynamic string semantics: The formal string is either (1) written by passing the address of the 
formal string descriptor and the string to be copied to STR$COPY_DX, STR$COPY_R, 
LIB$SCOPY_DXDX, LIB$SCOPY_R_DX, OTS$SCOPY_DXDX, or OTS$SCOPY_R_DX, or 
(2) allocated by calling STR$GET1_DX, LIB$SGET1 _DD, or OTS$SGET1_DD and written in 
pieces. Only the length and address of the descriptor is modified by any of the preceding 
dynamic string resource allocation procedures. 

The two methods that you can choose for a procedure's interface specification to return a string 
as an output string parameter (or function value) are: 

• Use fixed-length semantics (regardless of the class code in the descriptor passed by the calling 
program). 

• Use the semantics indicated in the descriptor passed by the calling program. If DSC$B_CLASS 
contains DSC$K_CLASS_S = 1 or DSC$K_CLASS_Z = 0, use fixed-length string semantics. If 
DSC$B_CLASS contains DSC$K_CLASS_D = 2, use dynamic string semantics, (preferred) 

With either semantics, a procedure also provides an optional, unsigned word output that indi¬ 
cates the length of the string in bytes, not including any space filling. If the string is truncated, the 
returned length reflects the truncation. Thus, the output parameter can always be used by the 
calling program to extract the significant data. (See Section 4.5.) 

14. A procedure cannot require its caller to pass a dynamic string descriptor. (See Section 4.5.) 

15. Some procedure interface specifications retain state information from one call to the next, even 
though the procedures are not resource allocating. The interface specification uses one of the 
following techniques to permit sequences of calls from independent parts of a program. These 
techniques either eliminate the use of static storage or overcome its limitations (in order of 
decreasing preference): 

• The interface specification consists of a sequence of calls to a set of one or more procedures — 
the first procedure allocates and returns (as an output parameter to the calling program): (1) the 
address of heap storage or (2) some other process-wide identifying value. This parameter is 
passed to the other procedures explicitly by the calling program, and the last procedure deallo¬ 
cates any heap storage or process-wide identifying value. (See Sections 2.4.3.2, 2.4.3.3, and 
3.3.1.) 

• The procedure's caller allocates all storage and passes the address on each call. (See Sections 
2.4.3.1 and 3.3.2.) 

• The interface specification consists of a single call, where the calling program passes the 
address of one or more action routines and arguments to be passed to them. The procedure 
calls the action routine(s) during its execution. Results are retained by the procedure across 
calls to the action routine(s). (No static storage used. See Section 2.4.2.) 
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• The interface specification consists of a sequence of calls to a set of one or more procedures. 
The first procedure, among other things, saves the contents of any still active static storage on a 
push down stack in heap storage, and the last procedure, among other things, restores the old 
contents of static storage. Thus, static storage is made available for implicit parameters to be 
passed from one procedure to the next in the sequence of calls (unknown to the calling 
program). However, if an exception can occur anywhere in the sequence, the calling program 
must establish a condition handler that calls the last procedure in the event of a stack unwind 
(to restore the old contents of static storage). (See Section 3.3.3.) 

16. A procedure does not assume that the implicit outputs of procedures that it calls will remain 
unchanged if subsequently used as implicit inputs to those procedures or companion procedures. 
For example, your procedures cannot call SYS$CNTREG to contract the program region by the 
amount expanded previously by a call to SYS$EXPREG, since an intervening call to SYS$EXPREG 
might have been made by another procedure. Similarly, your procedure cannot make two calls to 
SYS$EXPREG and expect to have the second program region expansion allocated contiguously to 
the first. (See Sections 2.3.2 and 4.6.) 

17. A procedure executes in any VAX—11 access mode and at any address. (You should not assume 
that address bit 31 is always 0.) 

18. A procedure does not depend on AST interrupts being enabled to execute correctly if there are 
other coding methods available. Therefore when doing synchronous VAX-11 RMS I/O, RMS 
completion routines are not used. (See Section 4.6.) 

19. A procedure provides an interface to its callers that allows the callers to follow all required 
elements of this standard. 

20. A procedure does not call other procedures or system services if the resulting combination 
violates this standard from the calling program's viewpoint. A procedure can call other proce¬ 
dures or system services that do not follow optional elements of this standard. However, if the 
resulting combination (as seen from the calling program) does not follow the optional elements, 
the calling procedure must indicate such non-conformance in its documentation. (See Section 
4.6.) 

21. A procedure makes no assumptions about its environment other than those of this standard. In 
particular, to operate as specified, a procedure neither makes assumptions about nor places 
requirements on the so-called main program. 


A.3 Facility-Specific Part of the Standard 


The following elements apply to procedures that are part of a specific library facility. The following 
facility names represent library facilities: 


LIB General Utility and Resource Allocation Procedures 

MTH Mathematics Procedures 

STR String Procedures 

OTS Language-independent Support Procedures 
BAS BASIC—specific Support Procedures 

FOR FORTRAN-specific Support Procedures 

PAS PASCAL-specific Support Procedures 
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22. For MACRO procedures, the PSECT declarations for library code and data, respectively, are: 

♦ PSECT .fac$CODE PIC tUSRtC ON *PEL»LCL *SHR»EXE»RD »NOWRT 

♦ PSECT _fac$DATA PIC »USR,CON >REL >LCL »NOSHR > N 0 E X E»RD#NRT 

For BLISS procedures, the code and PUT declaration is: 

_fac$CODE READ t NOWRITE, EXECUTE t SHARE * PIC, CONCATENATE , 

ADDRESSING.MODE (GENERAL) 

and the OWN and GLOBAL (not available to caller) is: 

_ f a c $DAT A READ , WRITE , NOEXECUTE , NOSHARE , PIC* CONCATENATE , 

ADDRESSING.MODE (LONG.RELAT I YE) 

The linker sorts the leading underline last so library modules cannot cause truncation errors due 
to byte or word displacement addressing performed by the user program. 

NOTE 

For user PSECTs, replace "$" with in the preceding specifications; (see 

Section 4.2.3). 


23. A procedure's caller, at its option, can indicate omitted trailing optional parameters either by 
passing argument list entries that contain zero or by passing a shortened argument list. 

24. When a new version of a procedure replaces an existing library procedure, all added parameters 
are made optional to maintain upward compatibility. (See Section 2.2.6.) 

G eneral Utility Procedures (LIB) 

25. LIB procedures follow the facility-independent part of this standard described in Section A.2. 

26. LIB procedures pass arrays and strings by descriptor and input scalars by reference. LIB proce¬ 
dures can pass parameters by immediate value if the procedure provides a service for BLISS and 
MACRO programmers that is generally supplied as part of higher-level languages. For output 
string parameters (and string function values), LIB procedures use the semantics indicated in the 
descriptor passed by the calling program and return the string length as an optional output 
parameter. (See element 13 and Sections 2.2.2, 2.2.3, and 4.5.) 

27. The storage for input and output parameters can overlap at the option of the calling program. 
Therefore, a procedure is programmed to behave the same regardless of whether there is overlap. 

28. LIB procedures return error conditions to the caller using completion codes returned in RO as a 
function value rather than signaling. The condition value SS$_NORMAL (value of 1) is returned 
to indicate unqualified success. If LIB procedures call MTF1, STR or other procedures that signal, 
the LIB procedures set up a handler, such as LIB$SIG_TO_RET, to convert any software signals to 
return status. (See Section 2.2.6 and Chapter 5.) 

Mathematical Procedures (MTH) 

29. MTH procedures follow the facility-independent part of this standard described in Section A.2. 
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30. MTH procedures pass input scalars by reference. (See Section 2.2.2.) 

31. The storage for input and output parameters can overlap at the option of the calling program. 
Therefore, a procedure is programmed to behave the same regardless of whether there is overlap. 

32. MTH procedures signal errors since the function value (R0) is used to return a mathematical 
value. (See Section 2.2.6 and Chapter 5.) 

String Procedures (STR) 

33. STR procedures signal those errors that are programming errors, such as invalid descriptor, or 
environment errors that are very difficult to recover, such as exhausting virtual memory. Remain¬ 
ing errors are returned as function values. 

Language-Independent Support Procedures (OTS) 

34. Language-independent support procedures follow the higher-level, language-specific support 
procedure elements of this standard. (See elements 36—41.) 

35. Language-independent support procedures return output string parameters (and string function 
values) using the semantics indicated in the descriptor passed by the calling program. (See 
element 13 and Section 4.5.2.) 

Higher-Level Language-Specific Support Procedures (BAS, FOR, PAS) 

36. Higher-level language-specific support procedures are programmed so that, combined with the 
language-specific program unit, they follow the facility-independent part of this standard as seen 
from a program calling the program unit, except where prevented by the semantics of a language 
standard. 

37. The standard call linkage is recommended, especially for large procedures that perform signifi¬ 
cant computation. However, JSB and other non-standard linkages can be used with no corre¬ 
sponding standard call entry point, since most language-specific support routines are not 
intended to be called explicitly by users. To ensure compatibility between compiler generated 
code and JSB entry points, each JSB entry point name ends in _Rn where n indicates the highest 
register modified or used as an input parameter. To ensure that all registers will be correctly 
restored when an unwind occurs, the compiler-generated code must save at least R2 thru Rn in its 
entry mask and the JSB code support routines cannot save, reference, or modify Rn + 1 thru R11. 
(See Section 2.1.) 

38. If a particular functional capability already exists in a LIB, MTH, OTS, or STR facility, then those 
procedures should be called by other language-specific procedures rather than implementing 
their own algorithms. 

39. Higher-level language support procedures pass input scalars by immediate value if they are 32 
bits or less, input scalars by reference if they exceed 32 bits, output scalars by reference, input 
and output arrays by reference or by descriptor, and input and output strings by descriptor. (See 
Sections 2.2.2 and 4.5.) 

40. If a higher-level language statement does not indicate an error action, the error is signaled. 
Otherwise, higher-level language support procedures return a completion code to the caller on 
an error, where a compiled code check of R0 would not be an excessive speed or space penalty. 
However, when the penalty is excessive, the procedure can retain the error transfer address in the 
first of a series of calls, and transfer directly to it on an error after removing the stack frame. (See 
Section 2.2.6 and Chapter 5.) 
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41. For I /O errors that are signaled, the user PC is included as one of the FAO parameters so the user 
PC can be included in the message. Thus, the PC can be included even if traceback is disabled. 
(See Section 5.3.) 


A.4 AST-Reentrant Procedures (Optional) 

The following elements are required for all AST-reentrant procedures. To be AST-reentrant, a proce¬ 
dure must execute correctly while allowing any procedure (including itself) to be called between any 
two instructions. The other procedure can be an AST-level procedure, a condition handler, or 
another AST-reentrant procedure (see Chapter 6). A procedure that uses no static storage and calls 
only AST-reentrant procedures is automatically AST-reentrant. (See element 15 for ways to eliminate 
the use of static storage.) 

42. A procedure that uses static storage uses one of the following methods (or equivalent) to be called 
from AST and non-AST levels (in order of decreasing preference): 

• Perform access and modification of the data base in a single uninterruptible instruction. (See 
Section 6.3.1.) 

• Detect concurrency of data base access with "test and set" instructions at each access of the 
data base. (See Section 6.3.2.) 

• Keep a call-in-progress count incremented upon entry to the procedure and decremented upon 
return. The count is used as an index into separately allocated areas. (See Section 6.3.3.) 

• Disable AST interrupts on entry to the procedure and restore the state of the AST enables on 
return. The procedure must also establish a condition handler that restores the state of the AST 
enables in case an exception condition or stack unwind occurs. Since this technique could 
affect the real time response of the calling program, it must be documented if used. Further¬ 
more, the length of time that ASTs are disabled should be minimized. (See Section 6.3.4.) 

43. If a procedure performs I/O from the AST level by calling VAX-11 RMS $GET and $PUT system 
services, it must check for the record stream active error status (RMS$_RSA). If the error is 
encountered, the procedure issues the $WAIT system service and then retries the $GET or $PUT 
system service. (See Section 6.4.) 

A.5 Shareable Images (Optional) 

A procedure that adheres to the following elements can be included in a shareable image at any time. 

44. A procedure's code is position-independent. All references to relocatable data use PC relative 
addressing mode (n(PC)). All references to absolute locations, such as VMS System Service entry 
points, use absolute addressing mode (@(PC) + ). (See Section 1.1.1.) 

45. The data need not be position-independent. However, for improved performance, data should be 
initialized to zero at compile or link time to avoid either position-independent constants or 
position-dependent addresses. (See Section 4.3.1.) 

46. A procedure cannot use LIB$INITIALIZE to initialize data, since a shareable image cannot make a 
PSECT contribution to a user program at link time. (See Section 4.3.4.) 


A-8 VAX-11 Modular Programming Standard 



A.6 Upwards Compatible Shareable Images (Optional) 

To be compatible with all future versions of the shareable image, shareable image procedures follow 

these additional rules: 

47. A procedure's entry points are vectored using a separate MACRO module containing TRANSFER 
declarations. (See Section 7.2.) 

48. A procedure's code and data are position-independent. Because VMS can provide a demand- 
zero page when the page is first accessed, initializing the data to zero is recommended. 

A.7 Modular Programming Recommendations (Optional) 

The following elements are recommended, so modular procedures will be similar in form and format 

and thereby more usable. These recommendations deal with matters of style. Therefore, nonconfor¬ 
mance to them will not affect modularity and need not be documented. 

49. The order of required parameters should be the same as that of the VAX-11 hardware instruc¬ 
tions, namely, read, modify, and write. Optional parameters follow in the same order. However, 
according to the VAX-11 Procedure Calling Standard, if a function value cannot be represented 
in 64 bits, the first parameter specifies where to store the function value, and all other parameters 
are shifted one position to the right. (See Section 2.2.5.) 

50. A procedure should not have static storage unless it: (1) is a process-wide, resource-allocating 
procedure, or (2) must retain results for implicit inputs on subsequent activations. Most of the 
techniques in element 15 avoid static storage. If a procedure cannot eliminate static storage and 
does not need to retain information from one procedure activation to the next, it writes each 
static storage location before the first read access to it. (See Section 2.4 and Chapter 3.) 

51. If a procedure produces human-readable text and outputs it to a file or device by default, it 
provides the caller with the option of specifying a parameter that consists of an action routine to 
accept the text instead (see Section 2.6). The procedure calls the action routine with each line of 
text as a string containing a leading space (in case of FORTRAN carriage control) and no ASCII 
CR, LF, VT, or FF. Thus, the string can be put in three of the four types of record attribute files 
(CR, FTN, or PRN). The string is passed by descriptor and should not exceed 80 characters so it 
can be printed on most terminals. The action routine returns a condition value that is either: 
success (the procedure continues), or failure (the procedure stops further calls to the action 
routine). (See Sections 2.5 and 4.7.) 

52. A procedure that allocates process-wide resources provides an entry point that shows the state of 
the resource (for debugging and performance statistics). If such an entry point produces human 
readable output to a file or device, it must also conform to element 51. (See Sections 2.6, 4.4, 
and 4.7.) 

53. Timing procedures and resource allocation procedures should make statistics available for per¬ 
formance evaluation and debugging. (See Section 2.7.) Such procedures should provide two 
entry points that accept an input parameter code (1,...,n) indicating the desired statistic and 
return a completion status in R0: 

fac$SHOW_name 

Provides formatted strings according to element 51. A zero input parameter code requests all 
available statistics and can produce one or more calls to the action routines, each of which 
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passes a single line. If the calling program does not supply the optional action routine parameter, 
the string(s) are output to SYS$OUTPUT. 

fac$STAT_name 

Returns the binary value of the statistic you want. 

(User versions use _ instead of $) 

54. The recommended format for prompt strings is: an English word or words followed by a colon (:), 
one space, and no CRLF. (RSX utilities use > with no trailing spaces.) 

55. Procedures should follow structured programming guidelines. This includes placing a minimum 
number of procedures—typically one—in a module, and arranging procedures in levels of 
abstraction. Related procedures, such as those that access the same static storage, should be in 
the same module. (See Section 4.1.) 

56. Procedures should be placed in a module that is documented with a module description. Every 
procedure should be documented with a procedure description. (See Section 2.7 for the 
template.) 

57. File names should be identical to the first nine characters of the module name, with $ and _ 
characters omitted. (See Section 4.2.2.) 

58. When symbol definitions are to be coordinated between more than one module (such as control 
blocks, procedure parameter values, and completion status codes), the definitions should be 
centralized in one place. The preferred method is for procedures to make external declarations to 
obtain the symbolic value. Then, a source module can be compiled or assembled independently 
from any other source files. When the use of external symbols is not practical or possible, 
procedures should use these techniques (see Section 4.2.4): 


• MACRO: 

• BUSS: 

• BASIC: 

• FORTRAN: 

• PASCAL: 


Macro library file 
REQUIRE or LIBRARY file 
APPEND file 
INCLUDE file 
%INCLUDE file 


59. Procedure name formats contain a verb followed by the object of the action: for example, 
LIB$GET_VM and LIB$FREE_VM. (See Section 2.1.) 

60. JSB calling sequences should be avoided because they are not available to most languages. When 
a procedure uses a JSB entry point, it should also provide an equivalent call entry point. 

61. Instructions and statements are uppercase, while comments are in uppercase and lowercase. A 
space follows every comma, semicolon, and exclamation point. A space precedes a left paren¬ 
thesis or square bracket (except in MACRO), but not a left angle bracket. Block comments start in 
column 1 and have the following form (use ; or ! depending on the language): 


; + 

; Put one or more lines of block comment here 


62. Use symbols rather than numbers in the body of the procedure. In MACRO, procedures use 
numeric labels (n$) in logical blocks of code that fit on the same listing page. (See Section 4.2.5.) 
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A.8 Change History 

The following changes have been made to the VAX-11 Modular Programming Standard from the 
previous version of the VAX-11 Guide to Creating Modular Library Procedures (AA-H500B-TE, 
April, 1980): 

1. Modified Element 4; maximum length of a procedure entry point name 

2. Modified Element 13; varying-length string semantics 

3. Expanded Section A.3; PLI facility name and number 
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Appendix B 
Naming Conventions 


The conventions described in this appendix were derived to aid implementors in producing meaning¬ 
ful public names. Public names are all names known to the linker ("global") in parameter or macro 
definition files. 

Reasons for the public naming conventions include the following: 

• Using reserved names ensures that customer-written software is not invalidated by subsequent 
releases of DIGITAL products which add new symbols. 

• Using definite patterns for different uses lets you judge the type of object being referenced. For 
example, the form of a macro name differs from that of an offset, which differs from that of a status 
code. 

• Using certain codes in a pattern associates the size of an object with its name. This increases the 
likelihood that the reference uses the correct instructions. 

• Using a facility code in symbol definitions gives the reader an indication of where the symbol is 
defined. Separate groups of implementors can choose facility codes names that do not conflict with 
one another. 

Never define local synonyms for public symbols. You should use the full public symbol in every 
reference to give maximum clarity to the reader. 

B.1 Public Symbol Patterns 

All DIGITAL public symbols contain a dollar sign. Thus, customers and applications developers are 
strongly advised to use underscores instead of dollar signs to avoid conflicts. 

Public symbols should be constructed to convey as much information as possible about the entity 
they name. These are used both in a module and globally between modules of a facility. All names 
that might ever be bound into a user's program must follow the rules for public names; for internal 
names, you can use a double dollar sign convention. (See the following numbers 3 and 5.) However, 
DIGITAL is free to change the interface of entities identified with more than one dollar sign. 
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Public names are of the following forms: 

1. Service macro names are of the form: 

Smacroname 

A trailing _S or _A distinguishes the stack and separate arglist forms. These names are in the 
system macro library and represent a call to one of many facilities. The facility name usually is 
not in the macro name. 

2. Facility-specific public macro names are of the form: 

$facility_macroname 

3. System macros using local symbols or macros always use those of the form: 

$facility$macroname 

This is the form to be used both for symbols generated by a macro and included in calls to it, and 
for internal macros that are not documented. 

4. Status codes and condition values are of the form: 
facility$_status 

5. Global entry point names are of the form: 
facility$entryname 

Global entry point names intended for use only in a set of related procedures (but not by any 
calling programs outside the set) are of the form: 

facility$$entryname 

6. Global entry point names that have nonstandard calls (JSB entry point names) are of the form: 
facility$entryname_Rn 

where values in registers RO to Rn are not preserved. The caller of such an entry point must 
include at least registers R2 through Rn in its own entry mask so a stack unwind correctly restores 
all registers. 

7. Global variable names are of the form: 
facility$Gt_variablename 

The G stands for global variable, and the t represents the type of variable, as defined in Section 
B.2. 

8. Addressable global arrays use the A (instead of the G) and are of the form: 
facility$At_arrayname 

The A stands for global array, and t represents the type of array element, as defined in Section 
B.2. 

9. In the assembler, public structure offset names are of the form: 
structure$t_fieldname 

The t represents the data type of the field, as defined in Section B.2. The value of the public 
symbol is the byte offset to the start of the field in the structure. 


B—2 


Naming Conventions 



10. In MACRO, public structure bit field offset and single bit names are of the form: 
structure$V_fieldname 

The value of the public symbol is the bit offset from the start of the containing field (not from the 
start of the control block). 

11. In MACRO, public structure bit field size names are of the form: 
structure$S_fieldname 

The value of the public symbol is the number of bits in the field. 

12. In BLISS, the functions of the symbols in the previous three items are combined into a single 
name used to reference an arbitrary datum. Names are of the form: 

structure$x_fieldname 

where x is T for standard-sized data and x is V for arbitrary and bit fields. The macro includes the 
offset, position, size, and sign extension suitable for use in a REF BLOCK structure. Typically, this 
name is definable as: 

MACRO 

structure$V_fieldname = 
structure$T_fieldname, 

structure$V_fieldname, lassembler meaning 
structure$S_fieldname, 

<sign extension> %&; 


or 

FIELD 

structure$V_fieldname = 

[structure$T_fieldname, 

structure$V_fieldname, 

structure$S_fieldname, 

<sign extension> %& ]; 

13. Public structure mask names are of the form: 
structure$M_fieldname 

The value of the public symbol is a mask with bits set for each bit in the field. This mask is not 
right justified; rather, it has structure$V— fieldname zero bits on the right. 

14. Public structure constant value names are of the form: 
structure$K_constantname 

15. PSECT names are of the form: 
facility$mnemonic 

and when put in a library: 

_facility$mnemonic 
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16. Module names are of the form: 
facility$mnemonic 

The module is stored in a file with file name facilitymnemonic. 

17. Public structure definition macro names are of the form: 
$facility_structureDEF 

Invoking this macro defines all the structure$xxx symbols. 


Example of usage: 

IOCSIODONE 

UCB$B_FORK_PRI 

UCB$I_STATUS 

CRB$M_BUSY 

CRB$V_BUSY 


Entry point of the routine IODONE in the I/O subsystem. 

Offset in the UCB structure to a byte datum containing the fork priority. 
Offset in the UCB structure to a longword datum containing status bits. 
Mask pattern for the busy bit in the CRB structure. 

Bit offset in the CRB structure of the busy bit 


B.2 Object Data Types 

The following letters are used for data types or are reserved: 

Letter Data Type or Usage 

A address (*) 

B byte integer 

C single character (*) 

D double precision floating 

E reserved to DIGITAL 

F single precision floating 

G general value (*) 

H integer value for counters (*) 

I reserved for integer extensions 

J reserved to customers for escape to other codes 

K constant 

L longword integer 

M field mask 

N numeric string (all byte forms) 

O reserved to DEC as an escape to other codes 
P packed string 

Q quadword integer 

R reserved for records (structure) 

S field size 

T text (character) string 

U smallest unit of addressable storage (*) 

V field position (assembler); field reference (BLISS) 

W word integer 

X context dependent (generic) 

Y context dependent (generic) 

Z unspecified or non-standard 

N, P, and T strings are typically variable-length. In structures or I/O records, they frequently contain 
a byte-sized digit or character count preceding the string. If so, the location or offset is to the count. 
Counted strings cannot be passed in CALLs; instead, a string descriptor is generated. 
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The letters A, C, G, H, and U should be used in preference to L, B, L, W, and B when transportability 
between various DIGITAL machine architectures is involved. This table defines their sizes: 


Letter 

16-bits 

32-bits 

36-bits 

A 

16 

32 

18 

C 

8 

8 

7 

G 

16 

32 

36 

H 

16 

16 

18 

U 

8 

8 

36 


B.3 Facility Prefix Table 

The following list shows some of the facility prefixes for DIGITAL-supplied software. This list wil 


grow as 

new facility prefixes are chosen. You should not 

use a i 

common 

place. 

Cond 

Prefix 

Facility 

<27: 

BAS 

BASIC support 

26 

BLI 

BLISS transportable support 

20 

B32 

BLISS-32 support 

27 

COB 

COBOL support 

25 

FOR 

FORTRAN support 

24 

LIB 

General Utility 

21 

MTH 

MatFi 

22 

OTS 

Language independent (Object Time System) 

23 

PAS 

PASCAL support 

33 

PLI 

PL/I support 

30 

RMS 

RMS internals and status codes 

1 

SORT 

VAX-11 SORT 

28 

SS 

System Service Status Codes 

0 

STR 

String 

36 

XPO 

BLISS transportable 

32 


Individual products such as compilers also get unique facility codes formed from the product name. 
They must be signed out in the registry. You should choose facility prefixes to avoid conflict with file 
types. 

Structure name prefixes are typically local to a facility. Refer to the individual facility documentation 
for its structure name prefixes. This method does not cause problems, since these names are not 
global and are therefore not known to the Linker. They become known at assembly or compile time 
only by explicitly invoking the macro defining the facility structure. 

Note 

DIGITAL does not provide a registration service for the customer facility codes. 
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Appendix C 

Notation for Describing Procedure Parameters 


C.1 Routine Interface Types 

To achieve the VAX-11 goal of being able to mix languages in a program, all routines are 
designed with certain common attributes. The data types and mechanism passing rules are 
designed to maximize the capability of your software at the callable procedure level to interface 
to software written by other users. A common notation is used to express the specification of 
the interface. 

The access types, data types, mechanisms, and parameter forms are defined in the VAX-11 
Run-Time Library Reference Manual. A procedure interface design must specify the data types. 
Four other considerations are also important: 

1. Whether the routine follows the VAX-11 procedure calling standard 

2. Whether its scalar input parameters are by immediate value or by reference 

3. How output strings are returned (discussed in the next paragraph) 

4. Whether the routine has a function value and whether the value is a status code or a scalar 
result 

In any facility, it is generally preferable to have only one style of these interface choices. Other 
combinations can be chosen, but the prospect of user confusion must be weighed against the 
possible inefficiency of forced consistency. 

There are three string semantics for returning a string to a calling program as an output parame¬ 
ter or a function value: 

• Fixed-length string semantics: The called procedure writes the string starting at the address 
specified in the descriptor and space fills or truncates on the right. It does not modify the 
contents of the descriptor. 

• Dynamic string semantics: The called procedure allocates the string buffer and places both 
the address and the length into the dynamic descriptor by calling library dynamic string allo¬ 
cating procedures. 
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• Varying string semantics: The called procedure writes the string starting at the address specified in 
the descriptor. The current-length field of the descriptor is updated to reflect its new length. The 
address and the maximum-length field are not modified. 

The calling program can always pass a fixed-length, dynamic, or varying string at its option to 
any procedure. 

There are two choices for the interface specification of a procedure: 

• Return string using fixed-length semantics (notation - .wt.ds) 

• Return string using either fixed-length, dynamic, or varying semantics as specified by the 
caller in the descriptor (notation - .wt.dx) 

The actual choice depends on the environmental assumptions made in the procedure design. 

C.2 Parameter Descriptions 

A concise, language-independent notation describes each procedure parameter. The notation 
is a compatible extension of the one used in the VAX Architecture Handbook. 

The notation specifies for each parameter: 

1. A mnemonic name 

2. The type of access the procedure will make (read, write, ...) 

3. The data type of the parameter (longword, floating, ...) 

4. The argument passing mechanism (immediate value, reference, descriptor) 

5. The form of the parameter (scalar, array, ...) 

If a parameter is an address saved for later access by another procedure, the notation should 
reflect the ultimate access made by the second procedure. 

C.2.1 Procedure Parameter Characteristics 

Subroutines are described as: 

CALL subroutine_name(parameter1, parameter,..., parametern) 

Functions are described as: 

function-value = function_name(parameter1, parameter,..., parametern) 

Parameter and function-value are described as: 

<name>.<access typexdata type>.<passing mechanismxparameter form> 

where: 

1. <Name> is a mnemonic for the procedure formal specifier or function value specifier. 
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2. <Access type> is a single letter denoting the type of access that the procedure will (or can) 
make to the argument: 

a - Reserved for use in the VAX Architecture Handbook (address). Not used here since the 
object pointed to is specified. 

b - Reserved for use in the VAX Architecture Handbook (branch destination). Not used here 
since a branch destination cannot be a procedure formal argument. 

c - Parameter is an address of a procedure to be (optionally) called after stack unwound 
(return). No <data type> field is given, since the argument is a sequence of 
instructions. 

f - Parameter is an address of a function to be (optionally) CALLed without unwinding the 
stack. The <data type> field indicates the data type used to represent the function (ZEM 
or BPV). Immediately following ZEM or BPV is the data type of the function value. For 
example, func.fzeml.r indicates that the argument list entry contains the address of a 
function that returns a signed longword value in RO. 

j - Parameter is an address to which to (optionally) jump after the stack is unwound 
(return). No <data type> field is given, since the argument is a sequence of instruc¬ 
tions, such as FORTRAN ERR = . 

m - Parameter can be modified, that is, read and written. 

r - Parameter can be read only. 

s - Parameter is an address of a procedure subroutine to be (optionally) called without 
unwinding the stack. The <data type> field indicates the data type used to represent 
the subroutine (ZEM or BPV). 

v - Reserved for use in the VAX Architecture Handbook (variable bit field), 
w - Parameter can be written only. 

3. <Data type> is a letter denoting the primary data type with trailing qualifier letters to further 
identify the data type. Note that the routine must reference only the size specified to avoid 
improper access violations. 


Code 

Letters 

Use 



Atomic Data Types 

0 

z 

Unspecified 

2 

bu 

Byte logical (unsigned) 

2 

c 

Single character 

2 

u 

Smallest unit for addressable storage 

3 

wu 

Word logical (unsigned) 

4 

lu 

Longword logical (unsigned) 

4 

a 

Virtual address 

4 

cp 

Character pointer 

4 

Ic 

Longword containing a completion code 

5 

qu 

Quadword logical (unsigned) 

6 

b 

Byte integer (signed) 

6 

arb 

Byte containing a relative virtual address (*) 

7 

w 

Word integer (signed) 


(continued on next page) 
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Code 

Letters 

Use 



Atomic Data Types 

7 

arw 

Word containing a relative virtual address (*) 

8 

1 

Longword integer (signed) 

8 

arl 

Longword containing a relative virtual address (*) 

9 

q 

Quadword integer (signed) 

10 

f 

Single-precision F_floating 

11 

d 

Double-precision D_floating 

12 

fc 

F_floating complex 

13 

dc 

D_floating complex 

25 

ou 

Octaword logical (unsigned) 

26 

o 

Octaword integer (signed) 

27 

8 

Double-precision G_floating 

28 

h 

Quadruple-precision H_floating 

29 

gc 

G_floating complex 

30 

he 

H_floating complex 

31 

cit 

COBOL intermediate temporary 



String Data Types 

1 

V 

Bit string, aligned 

■ ■ 

t 

Character-coded text string 

I 

nu 

Numeric string, unsigned 


nl 

Numeric string, left separate sign 

17 

nlo 

Numeric string, left overpunched sign 

18 

nr 

Numeric string, right separate sign 

19 

nro 

Numeric string, right overpunched sign 

20 

nz 

Numeric string, zoned sign 

21 

P 

Packed decimal string 

34 

vu 

Bit string, unaligned 

37 

vt 

Varying character-coded text string 



Miscellaneous Data Types 


r 

Record 


X 

Data type indicated in descriptor 


zi 

Sequence of instructions 


zem 

Procedure entry mask 


dsc 

Descriptor (for use in descriptors) 


bpv 

Bound procedure value 


blv 

Bound label value 


adt 

Absolute date and time 

* - arl, arw, and arb are self-relative addresses using the same format as the 

hardware displacements. That is, the self-relative address is a signed offset in 

bytes with respect to the first byte following the parameter. 


4. <Passing mechanism> is a single letter indicating the parameter passing mechanism that the 
called routine expects: 

d - Descriptor, that is, call by descriptor where the contents of the parameter list entry 
is the longword address of a descriptor. The descriptor is two or more longwords 
that specify further information about the parameter; see Appendix C of the VAX-11 
Run-Time Library Reference Manual. Note that when <passing mechanism> is d, 
<parameter form> must be present to indicate the type of descriptor. 

r - Reference, that is, call by reference where the contents of the parameter list entry is the 
longword address of the argument of the indicated data type. If the parameter is a scalar 
of the indicated data type or is a label, <parameter form> must be absent. If the param¬ 
eter is an array, <parameter form> must be present. 
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v - Immediate value, that is, call by immediate value where the contents of the parameter 
list entry is itself the parameter of the indicated data type. Note that call by immediate 
value parameter list entries are always allocated as a longword. The quadword data 
types can be used as values only for function values, never as a formal parameter. Note 
also that the VAX-11 calling standard requires that <access type> must be r whenever 
<passing mechanism> is v, except for function values where <access type> is always w 
and <passing mechanism> is usually v. 

5. <Parameter form> is a letter denoting the form of the argument: 


Code 

Letters 

Meaning 

- 

- 

Null means scalar of indicated data type. 

- 

X 

Any one of the supported string descriptors, as specified by the calling program in 
the DSC$B_CLASS field of the descriptor that it passes to the called procedure. 

- 

xl 

Either fixed-length or dynamic descriptor, as indicated by the calling program in the 
DSC$B_CLASS field of the descriptor that it passes to the called procedure. 

1 

s 

Scalar or string descriptor, that is, call by descriptor, where the contents of the 
parameters list entry is the longword address of a 2 -longword scalar descriptor. 
When the data type field (DSC$B_DTYPE) indicates ASCII text (DSC$K_DTYPE_T), 
the descriptor contains the length, data type, and address of a fixed-length string. 
When the string is written, neither the length nor the address fields in the descriptor 
are modified, and the string is filled with trailing spaces or a separate parameter is 
updated with the written length. 

2 

d 

Dynamic string descriptor, that is, passed by descriptor, where the contents of the 
parameter list entry is the longword address of a 2 -longword string descriptor of the 
same format as that of s. However, when the string is written, both the length and 
address fields may be modified. Space is allocated dynamically by routines in the 
procedure library. 

4 


Array reference or array descriptor, that is, call by reference or call by descriptor, as 
indicated by <parameter mechanism>. For array call by reference, the contents of 
the parameter list entry is the address of an array of items of the indicated data type. 

The length is fixed, implied by entries in the array (for example, a control block), 
determined by another parameter, or specified by prior agreement. For array call by 
descriptor, the contents of the parameter list entry is the longword address of an 
array descriptor block. (See Appendix C of the VAX-11 Run-Time Library Reference 
Manual.) 



5 

P 

Procedure descriptor, that is, passed by descriptor, where the contents of the 
parameter list entry is the longword address of a 2 -longword procedure descriptor. 

The descriptor contains the address of the procedure and the data type that the pro¬ 
cedure returns if it is a function. <Access type> must be c, f, j, or s. 

9 

sd 

Scalar decimal descriptor. First two longwords are like the s descriptor. The third 
longword contains scale factor byte, and number of decimal digits byte. 

10 

nca 

Noncontiguous array descriptor. Used when the array elements are not stored con¬ 
tiguously to one another. 

11 

vs 

Varying string descriptor. Used for varying strings consisting of two fixed-length 
areas allocated contiguously with no padding between. 

12 

vsa 

Varying string array descriptor. Used to specify an array of varying strings where 
each varying string has the same maximum length. 

13 

ubs 

Unaligned bit string descriptor. Used to pass an unaligned bit string that starts on an 
arbitrary bit boundary and ends on an arbitrary bit boundary. 

14 

uba 

Unaligned bit array descriptor. Used to specify an array of unaligned bit strings. Ele¬ 
ments of the array can be accessed directly using the VAX-11 variable bit field 
instructions. 
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C.2.2 Optional Parameters and Default Values 


The caller can omit optional parameters at the end of a parameter list by passing a shortened 
list. The caller can also omit optional parameters anywhere by passing a zero value as the con¬ 
tents of the parameter list entry. However, a caller cannot omit a parameter that is not indicated 
as optional. The called procedure is not obligated to detect such a programming error. 
Optional parameters are enclosed in square brackets, as follows: 

CALL FOR$READ_SU (unit.rb.v [,err.j.r [,end.j.r]]). 

An equal sign ( = ) after a parameter inside square brackets indicates the default value if the 
parameter is omitted, as in the following example: 

status.wlc.v = LIB$DELETE_LOGICAL (lognam.rt.dx [,tblflg.rl.r= 1]) 

Note 

VAX/VMS system services have optional parameters, but the list cannot be 
shortened. This type of optional parameter is indicated with the comma outside 
of the square brackets. For example: 

success.wlc.v = SYS$DELLOG([tblflg.rl.v], [lognam.rt.dx], [acmode.rl.v]) 

C.2.3 Repeated Parameters 

Parameters that can be repeated one or more times are indicated using ellipses, for example: 
CALL FOR$OPEN (keywd.rw.v,info.rl.v...) 

Repeated parameters that can be omitted entirely are indicated with ellipses inside square 
brackets, for example: 

CALL FOR$CLOSE ([logicaLunit.rl.v...]) 


C.2.4 Examples 

In the following statements, each parameter is described using the language-independent 
notation. 

sine_of_angle.wf.v = MTH$SIN (angle_in_radians.rf.r) 

CALL FOR$READ_SF (unit.rb.v, format.mbu.ra [,err.j.r [,end.j.r]]) 

Note that: (1) end can be omitted and that (2) err and end can both be omitted. However, unit 
and format must always be present. The parameter count byte in the parameter list specifies 
how many parameters are present. Alternatively, err, end, or both could have a parameter list 
entry equal to zero. 
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C.2.5 Summary Chart of Procedure Parameter Notation 

<name>.<access typexdata type>.<pass mechxparameter form> 


The following notation is used to define these characteristics: 



<access type> 


<data type> 

c 

Call after stack unwind 

a 

Virtual address 

f 

Function call (before return) 

adt 

Absolute date and time 

j 

JMP after unwind 

arb 

8 -bit relative virtual address 

m 

Modify access 

arl 

32-bit relative virtual address 

r 

Read-only access 

arw 

16-bit relative virtual address 

s 

Call without stack unwinding 

b 

Byte integer (signed) 

w 

Write-only access 

blv 

Bound label value 



bpv 

Bound procedure value 



bu 

Byte logical (unsigned) 



c 

Single character 



cit 

COBOL intermediate temporary 



cp 

Character pointer 



d 

D_floating 



dc 

D_floating complex 


<passing mechanism> 

dsc 

Descriptor (used by descriptors) 



f 

F_floating 

d 

By descriptor 

fc 

F_floating complex 

r 

By reference 

g 

G„floating 

V 

By immediate value 

gc 

G_floating complex 



h 

H__floating 



he 

H__floating complex 



1 

Longword integer (signed) 



Ic 

Longword return status 



lu 

Longword logical (unsigned) 



nl 

Num. string, It. separate sign 



nlo 

Num. string, It. overpunched sign 



nr 

Num. string, rt. separate sign 


<parameter form> 

nro 

Num. string, rt. overpunched sign 



nu 

Num. string, unsigned 



nz 

Num. string, zoned sign 

- 

Scalar 

o 

Octaword integer (signed) 

a 

Array reference or descriptor 

ou 

Octaword logical (unsigned) 

d 

Dynamic string descriptor 

P 

Packed decimal string 

nca 

Noncontiguous array descriptor 

q 

Quadword integer (signed) 

P 

Procedure reference or dsc 

qu 

Quadword logical (unsigned) 

s 

Fixed-length string descriptor 

r 

Record 

sd 

Scalar decimal descriptor 

t 

Character-coded text string 

uba 

Unaligned bit string array dsc 

u 

Smallest addressable storage unit 

ubs 

Unaligned bit string desc 

V 

Aligned bit string 

vs 

Varying string descriptor 

vt 

Varying character-coded text str. 

vsa 

Varying string array desc 

vu 

Unaligned bit string 

X 

Class type in descriptor 

w 

Word integer (signed) 

xl 

Fixed-length or dynamic 

wu 

Word logical (unsigned) 


string descriptor 

X 

Data type in descriptor 



z 

Unspecified 



zem 

Procedure entry mask 



zi 

Sequence of instruction 
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The notation xy.z means that the argument is passed only to a user-supplied procedure, and 
can have any access type (x), data type (y), and passing mechanism (z). 

The order of parameters is generally: 

1. Required input (read, jump, function access) 

2. Required input/output (modify access) 

3. Required output (write access) 

4. Optional input (read, jump, function access) 

5. Optional input/output (modify access) 

6. Optional output (write access) 


Note 

JSB entry points accept parameters in the preceding order in registers starting 
at RO. 


Common combinations of the language-independent notation are: 


completion code: 

longword call by immediate value input arg: 
address of an array of signed words for input: 
address of a control block: 
address of a precompiled format statement: 
label to jump to: 

floating input call by reference arg: 

floating complex call by reference input arg: 

read only character string: 

output fixed-length string: 

output string by descriptor: 

user action routine that returns a cond. value: 


status.wlc.v =... 
no_of_pages.rlu.v 
array, rw.ra 
fab.mz.ra 
format.rbu.ra 
errorJabel.j.r 
angle_in_rad.rf.r 
angle.rfc.r 
string.rt.ds 
string.wt.ds 
string.wt.dx 
func.fzemlc.r 
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A 

Abstraction, levels of, 4—2 

Access types, 2-3, C-3 

Accessing libraries, 7-6 

Accessing shareable images, 7-5, 7-6f 

Action routines 

for controlling human readable output, 

2-15, A—9 
example, 4—25 
invoking, 4—24 

using, to avoid implicit parameters, 2—11 
Allocating identification numbers, 4—14 
Allocating process-wide resources, 1-4, 

4-12 to 4-15, A—3, A—9 
designing procedures for, 2—16, A—9 
identification numbers, 3-6 
methods of, 4—1 3 
storage 3-1 to 3-1 3 
Allocating storage, 3—1 to 3—13 
heap, 3—3 

heap, in BLISS, 3—11 
stack, 3-2 
static, 3—1, 3—6 
APPEND command (BASIC) 

for including parameter definitions, 4-6, A-10 
AST (asynchronous system trap), 6-1 to 6-7, A-8 
interrupts, 6—2, A—5 
interrupts, disabling, 6-6 
system services, 4—19 
AST-reentrant procedures, 1—4, A—8 
coding, 6-1 to 6-7 
AST routines 
using, 6-2 

Asynchronous system trap. 5ee AST 
(asynchronous system trap) 

B 

BBCC instruction, 6—5 
BBSS instruction, 6—5 
Bit strings. See Strings 
Block comments 

in source code, 4—7, A—10 
Branch instructions, 4—7 
branch on bit clear, 6—5 
branch on bit set, 6—5 

C 

Call-in-progress count, 6—6 
CALLG instruction, 1-1 
Calling Standard, VAX-11, 1-4, A-2 
CALLS instruction, 1-1 
Character strings. See Strings 


Checking return status, 5-3 to 5-5 
Coding modular procedures, 4—1 to 4—23 
checklist of steps for, 1—5 
rules and recommendations for, 4—3 to 4-7 
Comments 

block, in source code, 4-7, A-10 
Common Run-Time Procedure Library. See 
Run-Time Library 
COMMON storage 

using, to declare PSECTs, 4-5 
Completion code. See Return status 
Condition handling, 1—4 

by language support procedures, A-7 
by modular procedures, 5-1 to 5-12 
Condition identification 

(STS$V_COND_ID), field in 
condition value, 5-2 
Condition values, 2—7, 5—1 to 5—3 
defining symbols for, 5—5 to 5—6 
fields of, 5-2 

matching, with LIB$MATCH_COND, 5-6 
success, 5—5 
symbols, 2-3 

Creating a procedure activation environment, 
5-11 

Creating object module libraries, 7-1 
Creating shareable image libraries, 7—5 
Creating shareable images, 7—3, 7—4f 
Creating transfer vectors, 7-10 

D 

Data types, 2-3, C-3 
in global symbols, B—4 
$DCLEXH system service, 4—11 
Decimal strings. See Strings 
Default values, for parameters, C-6 
Descriptors 

classes, and string semantics, 4—16, A—4 
parameter passing mechanism, 2-6, C-4 
string, 2—6, C—4 
Designing modular procedures 
checklist of steps for, 1—5 
DIGITAL-supplied libraries, 1 —8f 
Disabling AST interrupts, 6—6 
Dispatch address 

adding to PSECT LIB$INITIALIZE, 4-11 
Documenting procedures and modules, 

2-17 to 2-22, A-10 
modules, 2—17 to 2—20 
modules, in BLISS, 2—19f 
modules, in MACRO, 2—18f 
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Documenting procedures and modules (Cont.) 
procedures, 2-20 to 2-22 
procedures, in BLISS, 2-22f 
procedures, in MACRO, 2—21 f 
procedures and modules, 2—22 
Dollar sign, in global symbols, B-2 

E 

Entry point names, 2—1 
Entry points 
JSB, A—10 
naming, A—10 

Environment, procedure activation 
creating, 5-11 

Error handling, 2—7. See also Condition handling 
by language support procedures, A—7 
by modular procedures, 5-1 to 5-12 
by Run-Time Library facilities, 2-7 
Error messages, 5-1 
Error status. See Return status 
Exit handlers, declaring, 4-11 
Explicit parameters, 2—3 

F 

Facilities 

naming, 2-2 
Run-Time Library, A—5 
user-defined, 2—3 
Facility number 

(STS$V_FAC_NO), field in condition value, 
5-2 

Facility prefixes, in global symbols, B-5 
First-time flag 

testing and setting, 4—9 to 4-11 

G 

Global names, 5-5 
choosing, B-1 to B-5 
patterns for, B—2 

Global symbols. See Global names 

GO TO statements, 4-7 

Grouping procedures, 4-3, 4-4f, A-2 

H 

Heap storage 
allocating, 3—3 
allocating, in BLISS, 3—11 
using, 3-11 to 3-1 3 
Human readable output 
controlling, 2—15, A—9 


I 

I/O channel numbers 
as example of process-wide identification 
numbers, 2-14 

Identification numbers, process-wide 
allocating, 3-6, 4-14 

passing, to avoid implicit parameters, 2-14 
IMAGELIB.OLB, default shareable image library, 
1-7 

Images, shareable 
creating, 7-3, 7-4f 
standards for, A-8 

standards for upward compatible, A—9 
Immediate value, parameter passing mechanism, 
C—5 

Implicit parameters, 2-8 to 2-14, A-5 
avoiding, 2—1 3f 
avoiding, example of, 2-12 
%INCLUDE directive (PASCAL) 
for including parameter definitions, 4-6, A-10 
INCLUDE statement (FORTRAN) 
for including parameter definitions, 4-6, A—10 
Initializing 

modular procedures, 4-7 to 4-12, A-3 
modular procedures, methods for, 4-8f 
static storage, 4-9 
Input-output 

performing, at AST—level, 6—7 
Input parameters, string, 4-15 
Insert queue instruction, 6—4 
INSQUE instruction, 6—4 
Interfaces to modular procedures 
designing, 2-1 to 2-22 
types of, C—1 
Internal signaling, 5—11 
Interrupts 

of a non-AST—reentrant procedure, 6—2 
AST, 6-2 

AST, disabling, 6—6 

J 

JSB entry points, A-10 
Jump instructions, 4—7 

L 

Levels of abstraction, 4—2f 
LIB$FREE_LUN 

using, to free logical unit number, 2—14 
LIB$FREE_TIMER 

as example of avoiding implicit parameters, 
2-14 
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LIB$GET_LUN 

using, to get logical unit number, 2-14 
LIB$INITIALIZE 

adding dispatch address to, 4-11 
mechanism for initializing, 4—8, 4—11, A—3 
LIB$INIT_TIMER 

as example of avoiding implicit parameters, 
2-14 

LIB$MATCH_COND 

using, to match condition values, 5-6 
LIB$SIGNAL 

signaling exception conditions, 5—1, 5—10, A—3 
LIB$STOP 

signaling exception conditions, 5-1, 5-10, A-3 
Libraries 

accessing, 7-6 
DIGITAL-supplied, 1 —8f 
executing an image that calls, 7—9f 
linking programs to, 7—8f 
object module, 1—2, 1—6 
object module, creating, 7-1, 7-2f 
procedure, 1—2f, 1—2, 7—1 to 7—11 
shareable image, 1-2, 1-6 
shareable image, creating, 7-5 
using and creating, 1-6 
LIBRARY command 
/CREATE qualifier, 7-1 
/SHARE qualifier, 7-5 
LIBRARY declaration (BLISS) 
for including parameter definitions, 4-5, A-10 
LINK command 

/NOSYSLIB qualifier, 1-7 
/NOSYSSHR qualifier, 1-7 
/OPTIONS qualifier, 7-5 
/SHAREABLE qualifier, 7-3 
Linker, VAX-11, 1-7 
options file, 7—5 

Linking programs to run-time libraries, 7—8f 
Logical unit numbers, 1—4 

as example of process-wide identification 
numbers, 2—14 
getting and freeing, 2—14 
Lowercase letters 

not recommended, for source code, 4—6, A—10 

M 

Macro libraries 

for including parameter definitions, 4—5, A—10 
Matching condition values 

with LIB$MATCH_COND, 5-6 to 5-7 
Message number (STS$V_MSG_NO) 
field in condition value, 5—2 


Modular procedures 
advantages of, 1-2 
checklist of steps for coding, 1-5 
coding, 4-1 to 4-23 
condition handling by, 5—1 to 5—12 
designing and coding, 2-1 to 2-22 
initializing, 4—7 to 4—12 
initializing, methods for, 4-8f 
rules and recommendations for coding, 

4-3 to 4-7 

signaling by, 5-10 to 5-12 
Modular Programming Standard, VAX—11, 1—1, 
A—1 to A—11 

facility-independent elements, A—2 to A—5 
facility-specific elements, A-5 to A-8 
recommendations, A—9 to A—11 
standards for AST—reentrant procedures, A—8 
standards for language support facilities, A—7 
standards for shareable images, A—8 
standards for the LIB facility, A—6 
standards for the MTH facility, A—6 
standards for the STR facility, A—7 
summary, 1—4 

Module description template 
BLISS, 2—19f 
MACRO, 2—1 8f 
Modules 

documenting, 2-17 to 2-22 
grouping procedures in, 4-3, A—2 
relocatable, 4-3 
MTH$RANDOM 

as example of avoiding implicit parameters, 
2-12 

N 

Names 

choosing, B-1 to B-5 
for condition values, 2—3 
entry point, A—2 
entry point, JSB, A—7 
facility, 2-2 
file, 4—3 

module, 4-3, A-2 
patterns for, B—2 
procedure, 2—1, A-10 
PSECT, 4-5 

Naming conventions, 1—4, B—1 to B—5 
for procedures, 2—1, A—10 
/NOSYSLIB qualifier (LINK command), 1—7 
/NOSYSSHR qualifier (LINK command), 1-7 
Notation for describing procedure parameters, 
C-1 to C—6 
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Notation for describing procedure parameters (Cont.) 
examples, C-6 
summary chart, C—6 

O 

Object data types, in global symbols, B—4 
Object module libraries, 1-2, 1-6 
creating, 7—1, 7—2f 
default, STARLET.OLB, 1-7 
Optional parameters, 2—6, C—6 
Options file, linker, 7-5 
Organizing modular procedures, 4-2f 
Output 

human readable, controlling, 2-15, A-9 
Output parameters 
strings, 4-15, A—4 

P 

Parameter forms, 2—3, C-5 
Parameter passing mechanisms. See 
Passing mechanisms 
Parameters 

characteristics of, 2-3 to 2-6, C-2 to C-6 
definition files, 4—5, A—10 
describing, 2-3, C—1 to C-6 
explicit, 2-3 

formal, definition of, A—3 
implicit, 2-8 to 2-14, A—5 
implicit, allocating, 2-8 to 2-10 
implicit, avoiding, 2—10 to 2-14 
input strings, accepting, 4-15 
notation for describing, 2-3, C—1 to C—6 
optional, 2—6, C-6 
order of, 2-7, A-9 
output string, 4-15, A—4 
passing string, 4-15 to 4-19, A—3, A-4 
Passing mechanisms, 2—3, C—4 
default, for high-level languages, 2-6 
for language support procedures, A—7 
for Run-Time Library facilities, 2-6 
Position-independent code (PIC), 1—4, 7—3 
required, for a shareable image, A—8 
Position-independent constant data, 4—5 
Prefixes, facility, in global symbols, B—5 
Procedure activation environment 
creating, 5-11 

Procedure Calling Standard, VAX—11. 

See Calling Standard, VAX-11 
Procedure description template 
BLISS, 2—22f 
MACRO, 2-2If 
Procedures 

AST-reentrant, A-8 

AST—reentrant, coding, 6—1 to 6—7 


Procedures (Cont.) 
definition of, 1-1 
documenting, 2-17 to 2-22 
grouping, 4—4f 

grouping, in a module, 4-3, A—2 
libraries, 1-2, 1 —3f 
modular, advantages of, 1—2 
modular, coding, 2-1 to 2-22, 4-1 to 4-23 
modular, definition of, 1-1 
modular, initializing, 4-7 to 4-12 
modular, rules and recommendations for 
coding, 4-3 to 4-7 
naming, 2-1, A—10 
organizing, in structured relationships, 

4—2f, 4-2 

Process-wide identification numbers 
allocating, 3-6, 4-14 

passing, to avoid implicit parameters, 2-14 
Process-wide resources 
allocating, 1-4, 4-12 to 4-15, A-3, A-9 
definition, 4-12 
methods of allocating, 4-13 
Program sections. See PSECTs 
Prompt strings 

recommended format for, A—10 
PSECTs 

adding dispatch address to LIB$INITIALIZE, 

4-11 

declaring, in BLISS, A—6 
declaring, in MACRO, A—6 
naming, 4-5 

using COMMON storage to declare, 4-5 
Put Message ($PUTMSG) system service, 5-1 

Q 

Queue instructions 

using, to avoid interrupts, 6-4 

R 

Race conditions, eliminating, 6—3 
Reference, parameter passing mechanism, 

2-6, C—4 

Relocatable modules, 4-3 
Remove queue instruction, 6—4 
REMQUE instruction, 6-4 
Repeated parameters, notation for designating, 
C-6 

REQUIRE declaration (BLISS) 
for including parameter definitions, 

4-5, A—10 

Resources, process-wide 
allocating, 1-4, 4-12 to 4-15, A-3, A-9 
definition, 4-12 

designing procedures for allocating, 2-16, A-9 
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Resources, process-wide (Cont.) 

methods of allocating, 4—13 
Return status, 2—7, 5—1 
checking, in BASIC, 5-4 
checking, in BLISS, 5-4 
checking, in FORTRAN, 5-4 
checking, in MACRO, 5-3 
checking, in PASCAL, 5-5 
Run-Time Library, VAX-11, 1-7, 7-1 

S 

Severity (STS$V_SEVERITY) 
field in condition value, 5—2 
Shareable image libraries, 1—2, 1—6 
accessing, 7—6 
creating, 7-5 

default, IMAGELIB.OLB, 1-7 
Shareable images, 1-2, 1-6, 7-1 to 7-11 
accessing, 7-5, 7-6f 
creating, 7—3, 7—4f 
standards for, A—8 

standards for upward compatible, A—9 
/SHAREABLE qualifier 
for LINK command, 7-3 
SHOW entry point 

timing and resource allocation procedures, 

2-1 6, A—9 

Signaling and condition handling 
by modular procedures, 5-12 
Signaling exception conditions, 5—10 to 5—12 
Spaces, optional, in source code, 4—7 
Stack storage 

allocating, 3-2 to 3—3 
using, 3-9 to 3-11 
using, in BASIC, 3-10 
using, in BLISS, 3—10 
using, in MACRO, 3—9 
using, in PASCAL, 3—10 

STARLET.OLB, default object module library, 1-7 
STAT entry point 

timing and resource allocation procedures, 
2-16, A—10 
Static storage 

allocating, 3—1, 3—6 
initializing, 4—9 

pushing down contents of, 3—7 to 3—8 
using, 3—6 to 3—9 
Stopping program execution 

by signaling mechanism, LIB$STOP, 5—10 
Storage, 1-4, 3-1 to 3-13 
choosing type of, 3—5 
heap, allocating, 3-3 
heap, allocating in BLISS, 3-11 
heap, using, 3—11 to 3—13 


Storage (Cont.) 
initializing, 4—8 
stack, allocating, 3—2 to 3—3 
stack, in BASIC, 3-10 
stack, in BLISS, 3-10 
stack, in MACRO, 3-9 
stack, in PASCAL, 3-10 
stack, using, 3-9 to 3-11 
static, allocating, 3—1, 3—6 
static, avoiding, A—4, A—9 
static, initializing, 4—9 
static, using, 3-6 to 3-9 
types of, 3-4f 

using, with resource-allocating procedures, 4-1 3 
String descriptors, 2—6, C—5 
Strings 

accepting input, 4—15 

passing, as parameters, 4—15 to 4-19, 

A—3 to A—4 
returning output, 4—15 
semantics for writing, 4-16, A-4 
Structured programming, 4—1 to 4—3, A—10 
STS$V_COND_ID, condition identification 
field in condition value, 5—2 
STS$V_FAC_NO, facility number 
field in condition value, 5-2 
STS$V_MSG_NO, message number 
field in condition value, 5—2 
STS$V_SEVERITY, severity 
field in condition value, 5—2 
Symbols, global 
choosing, B-1 to B-5 
condition value, 2—3 
condition value, defining, 5—5 to 5—6 
data types in, B—4 
dollar signs in, B—2 
facility prefixes in, B—5 
patterns for, B-2 
in place of numbers, 4—6, A-10 
underscores in, B—2 
System services, 1—4, 4—19 to 4-23 
AST services, 4—19 
change mode, 4-22 
condition handling, 4—21 
error message, 4—22 
event flag services, 4—1 9 
formatted ASCII output, 4—22 
I/O, 4-20 
logical name, 4—20 
memory management, 4—21 
modularity of, 4-19 to 4-23 
notes, 4-23 
process control, 4-20 
Record Management Services, 4—22 
timer and time conversion, 4—21 
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T 

Test and set instructions, 6-5 
to initialize procedures, 4-9 to 4—11 
Testing return status, 5-3 to 5—5 
Timing procedures 

avoiding implicit parameters with, 2-14 
designing, 2-16, A—9 
Transfer vectors, 1—5, 7—3 
creating, 7-10 


U 

Underscore, in global symbols, B—2 
Uppercase letters 

recommended, for source code, 4—6, A-10 
User action routines 

for controlling human readable output, 2-15 
using, to avoid implicit parameters, 2—11 

V 

VAX-11 Common Run-Time Procedure Library. 
See Run-Time Library 

VAX-11 Linker, 1-7. See also Linker, VAX-11 
VAX-11 Modular Programming Standard. 

See Modular Programming Standard , VAX- / / 
VAX-11 Procedure Calling Standard. See 
Calling Standard , VAX-11 
VAX—11 Run-Time Library. See Run-Time Library 
VAX/VMS system services. See System services 
Vectors, transfer, 1—5 
Virtual memory, 1-4. See also Storage 
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